How-to guides

Recipes for specific PyPI tasks.

• Cache packages for CI

  Put peryx between CI runners and pypi.org so runners share downloaded wheels.

• Serve a restricted or air-gapped network

  Use peryx as the approved path to PyPI or carry a warmed partial mirror into an isolated network.

• Proxy a private upstream

  Point peryx at Artifactory, GitLab, or any other PEP 503 index, with credentials.

• Compose virtual indexes

  Serve several indexes under one URL, give each cached index its own private layer, and chain virtual indexes.

• Publish packages

  Upload distributions with twine or uv, including wheels from older tooling and clients that declare one digest.

• Upload from a browser

  Publish one wheel or source distribution through the web UI with the same validation and storage path as twine and uv.

• Yank and delete packages

  Yank an uploaded release per PEP 592 or delete it outright, address a release by any equivalent version spelling, and manage a project named after a mutation verb.

• Publish from CI identities

  Exchange a GitHub Actions or GitLab CI OIDC identity for a short-lived, repository-scoped PyPI upload token.

• Diagnose Simple API serving

  Diagnose api-version 1.0, replace gpg-sig checks with served SHA-256 hashes, and handle trailing-slash redirects.

• Troubleshoot pip and uv

  Distinguish missing projects, offline misses, upstream failures, access denials, and upload limits.