PEP 694 – Upload 2.0 API for Python Package Indexes | peps.python.org
PEP 694 – Upload 2.0 API for Python Package Indexes PEP 694 – Upload 2.0 API for Python Package Indexes Author : Barry Warsaw <barry at python.org>, Donald Stufft <donald at stufft.io>, Ee Durbin <ee at python.org> PEP-Delegate : Dustin Ingram <di at python.org> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Packaging Created : 11-Jun-2022 Post-History : 27-Jun-2022 , 06-Jan-2025 14-Apr-2025 06-Aug-2025 27-Sep-2025 07-Dec-2025 26-Jun-2026 29-Jul-2026 Table of Contents Abstract Rationale Legacy API Endpoint Encoding Content Authentication Upload 2.0 API Specification Versioning Content Types Root Endpoint Authentication and Authorization Errors Publishing Session Create a Publishing Session Optional Index-specific Metadata Response Body Multiple Session Creation Requests Publishing Session Links Publishing Session Files Publishing Session States Complete a Publishing Session Atomic Publication and Conflicts Publishing Session Cancellation Publishing Session Status Session Status Retention Publishing Session Extension Publishing Session Token File Upload Session Create a File Upload Session Response Body File Upload Session Links File Upload Session States Complete a File Upload Session Cancellation and Deletion Replacing a Partially or Fully Uploaded File File Upload Session Status File Upload Session Extension Staged Previews File Upload Mechanisms Required File Upload Mechanisms http-post-bytes Server Specific File Upload Mechanisms Recommendations for Client Implementers General Workflow Parallel Uploads Multiple Sessions Session Management Suggested Command-Line Interfaces twine uv GitHub Actions Error Handling Legacy API Fallback Security Implications Name squatting potential Session authorization Malware hosting potential FAQ Does this mean PyPI is planning to drop support for the legacy upload API?
Can I use the upload 2.0 API to reserve a project name? Why is the project name required when creating a publishing session? Why is the version required when creating a publishing session? Open Questions Extensions to the Upload 2.0 Protocol Change History Copyright Abstract This PEP proposes an extensible API for uploading files to a Python package index such as PyPI. Along with standardization, the upload API provides additional useful features such as support for: a publishing session, which can be used to simultaneously and atomically publish all artifacts (wheels, sdists) in a package release; “staging” a release, which can be used to test uploads before publicly publishing them, without the need for test.pypi.org ; artifacts which can be overwritten and replaced, until a session is published; detailed status on the state of artifact uploads; new project creation without requiring the uploading of an artifact; a protocol to extend the supported upload mechanisms in the future without requiring a full PEP; these can be standardized and recommended for all indexes, or be index-specific.
This PEP does not propose a deprecation schedule for the legacy API. Rationale There is currently no standardized API for uploading files to a Python package index such as PyPI. Instead, everyone has been forced to reverse engineer the existing “legacy” API. The legacy API, while functional, leaks implementation details of the original PyPI code base, which has been faithfully replicated in the new code base and alternative implementations.
In addition, there are a number of major issues with the legacy API: It is fully synchronous, which forces requests to be held open both for the upload itself, and while the index processes the uploaded file to determine success or failure. It does not support any mechanism for parallelizing or resuming an upload. With the largest default file size on PyPI being around 1GiB in size, requiring the entire upload to complete successfully means bandwidth is wasted when such uploads experience a network interruption while the request is in progress.
The atomic unit of operation is a single file. This is problematic when a release logically includes an sdist and multiple binary wheels, leading to race conditions where consumers get different versions of the package if they are unlucky enough to require a package before their platform’s wheel has completely uploaded. If the release uploads its sdist first, this may also manifest in some consumers seeing only the sdist, triggering a local build from source.
Status reporting is very limited. There’s no support for reporting multiple errors, warnings, deprecations, etc. Status is limited to the HTTP status code and reason phrase, of which the reason phrase has been deprecated since HTTP/2 ( RFC 7540 ). Metadata for a release is submitted alongside the file. However, as this metadata is famously unreliable, most installers instead choose to download the entire file and read the metadata from there.
There is no mechanism for allowing an index to do any sort of sanity checks before bandwidth gets expended on an upload. Many error conditions, such as incorrect permissions or quota exhaustion could be checked prior to uploading files. There is no support for “staging” a release prior to publishing it to the index. Creation of new projects requires the uploading of at least one file, leading to “stub” uploads to claim a project name, wasting space.
The new upload API proposed in this PEP provides ways to solve all of these problems, either directly or through an extensible approach, allowing servers to implement features such as resumable and parallel uploads. The upload API this PEP proposes provides better and more standardized error reporting, a more robust release testing experience, and atomic and simultaneous publishing of all release artifacts. Legacy API The following is an overview of the legacy API.
For the detailed description, consult the PyPI user guide documentation . Endpoint The existing upload API lives at a base URL. For PyPI, that URL is currently https://upload.pypi.org/legacy/ . Clients performing uploads specify the API they want to call by adding an :action URL parameter with a value of file_upload . [1] The legacy API also has a protocol_version parameter, in theory allowing new versions of the API to be defined.
In practice this has never happened, and the value is always 1 . Thus, the effective upload API on PyPI is: https://upload.pypi.org/legacy/?:action=file_upload&protocol_version=1 . Encoding The data to be submitted is submitted as a POST request with the content type of multipart/form-data . This reflects the legacy API’s historical nature, which was originally designed not as an API, but rather as a web form on the initial PyPI implementation, with client code written to programmatically submit that form.
Content Roughly speaking, the metadata contained within the package is submitted as parts where the content disposition is form-data , and the metadata key is the name of the field. The names of these various pieces of metadata are not documented, and they sometimes, but not always match the names used in the METADATA files for package artifacts. The case rarely matches, and the form-data to METADATA conversion is inconsistent.
The upload artifact file itself is sent as a application/octet-stream part with the name of content , and if there is a PGP signature attached, then it will be included as a application/octet-stream part with the name of gpg_signature . Authentication Upload authentication is also not standardized. PyPI uses HTTP Basic Authentication with API tokens as the password and the username __token__ . Trusted Publishers authenticate via OpenID Connect and receive short-lived API tokens that are used in the same way.
Upload 2.0 API Specification This PEP proposes a multi-request workflow, which at a high level involves these steps: Initiate a publishing session , creating a release stage. Initiate file upload session(s) to that stage as part of the publishing session. Negotiate the spe
The rest of this page is on the live site.