Simple API format transition to PEP 691 JSON on /simple/ path

Direct answer

As of the latest publicly available information, PyPI has not published formal removal criteria for the legacy HTML Simple index, nor a firm sunset date or decision process for password-based uploads. Both transitions are documented as intent, but the final removal criteria and timeline remain unannounced.

Legacy HTML Simple index removal

Confirmed: The Simple API currently serves HTML at /simple/. PEP 691 defines a JSON representation, but no official release or removal date is documented.

Likely explanation: Removal of the legacy HTML representation will probably depend on client adoption metrics, telemetry showing JSON-capable clients dominate traffic, and a formal deprecation window announced after those thresholds are met. This follows the standard pattern for API deprecations on PyPI, but the exact thresholds are not published.

Password upload sunset

Confirmed: Password-based uploads remain supported for backward compatibility. Scoped API tokens and Trusted Publishing are the recommended paths, but no sunset date has been announced.

Likely explanation: The decision process probably follows PyPI's internal roadmap, community feedback, and a phased deprecation plan. Until an official notice is published, tooling should migrate to API tokens or Trusted Publishing but can retain password fallback.

Detecting the served representation

Clients should not assume a format. Use HTTP content negotiation and inspect response headers.

1. Content-Type: Check the response header. application/vnd.pypi.simple.v1+json (or application/json) indicates a PEP 691 JSON response; text/html indicates legacy HTML.
2. Accept header: Send Accept: application/vnd.pypi.simple.v1+json to request JSON. If the server cannot satisfy it, it may return HTML.
3. Link header: PEP 691 uses the Link header for pagination. Legacy HTML pagination uses query parameters. Presence of Link headers with rel="next" confirms JSON-style pagination.

Verification commands

To check the current representation for a package or the root index, issue a HEAD or GET request and inspect headers:

curl -sI https://pypi.org/simple/requests/ | grep -i content-type
curl -sI -H "Accept: application/vnd.pypi.simple.v1+json" https://pypi.org/simple/requests/ | grep -i content-type

Replace requests with the target package name. These commands are read-only and safe.

Planning under uncertainty

Because no sunset dates are published, index clients and upload tools should:

• Support both HTML and JSON parsing during the transition.
• Implement content negotiation via the Accept header rather than URL-based versioning.
• Migrate upload authentication to scoped API tokens or Trusted Publishing now, while retaining password fallback until an official deprecation notice.
• Monitor the PyPI blog, pypi.org status page, and packaging mailing lists for formal announcements.

Warehouse behavior can vary by deployment configuration, so verify against the specific index you target.

If your client currently fails on /simple/, the single most useful diagnostic is the exact Content-Type and Link headers returned for a specific package request, because that determines whether the failure is a format-detection bug or an unsupported pagination model.