Skip to content

PyPI Integration

OrbitRepos provides a full-featured PyPI repository, allowing you to host private Python packages and proxy public ones from PyPI.org. It supports the PEP 503 Simple API and PEP 691 JSON API for seamless integration with pip, twine, and poetry.

Overview

By using OrbitRepos for your Python packages, you gain a single source of truth for your team's artifacts. It supports:

  • Hosted Repositories: Private storage for your internal Python libraries.
  • Proxy Repositories: Low-latency caching of public packages from PyPI.org.
  • Group Repositories: A single URL to access multiple hosted and proxy repositories.

The PyPI handler is accessible at the /pypi/{repoName}/ route.

Prerequisites

Before you begin, ensure you have:

  • OrbitRepos instance running (see the Quick Start if you haven't set it up yet).
  • Python 3.8+ installed.
  • pip and twine installed (pip install twine).
  • An API Token or user credentials with deployer permissions.

Create a Repository

You can create a PyPI repository via the OrbitRepos Web UI or the Management API.

  1. Navigate to Repositories in the sidebar.
  2. Click Create Repository.
  3. Select PyPI as the format.
  4. Choose a Type:
    • hosted: For your private packages.
    • proxy: To cache packages from an upstream (e.g., https://pypi.org/simple).
    • group: To aggregate multiple repositories.
  5. Enter a Name (e.g., pypi-internal).
  6. Click Create.

Push / Publish Artifacts

To publish a package to a hosted PyPI repository, use twine.

1. Build your package

Ensure you have a setup.py or pyproject.toml in your project root, then build the distribution:

python -m build

2. Upload with Twine

Upload the generated files in the dist/ directory to OrbitRepos:

twine upload --repository-url http://localhost:8080/pypi/pypi-internal/ dist/*

export TWINE_REPOSITORY_URL=http://localhost:8080/pypi/pypi-internal/
export TWINE_USERNAME=admin
export TWINE_PASSWORD=admin
twine upload dist/*

Using API Tokens

We recommend using API Tokens instead of passwords for CI/CD environments. Use the token as the password and __token__ as the username.

Pull / Install Artifacts

To install packages from OrbitRepos, configure pip to use your repository URL.

One-time install

Use the --index-url flag to point to the Simple API endpoint:

pip install --index-url http://localhost:8080/pypi/pypi-internal/simple/ my-package

Permanent configuration

Add the configuration to your pip.conf (Linux/macOS) or pip.ini (Windows):

[global]
index-url = http://localhost:8080/pypi/pypi-internal/simple/
extra-index-url = https://pypi.org/simple

Simple API Endpoint

OrbitRepos automatically appends /simple/ to the repository URL to provide the PEP 503 compliant index. Both /pypi/{repo}/ and /pypi/{repo}/simple/ are supported.

Proxy Setup

A proxy repository allows you to cache packages from PyPI.org locally, reducing bandwidth and improving build reliability.

  1. Create a repository with type proxy.
  2. Set the Remote URL to https://pypi.org/.
  3. OrbitRepos will automatically append simple/ when communicating with the upstream if needed.
  4. Configure your local pip to point to the proxy repository's URL.

When you request a package, OrbitRepos will: 1. Check if the package exists in the local cache. 2. If not, fetch it from PyPI.org, cache it, and return it to you.

Troubleshooting

Authentication Failed

Ensure your user has at least deployer permissions for the repository. If using an API Token, verify it hasn't expired.

404 Not Found

Double-check the repository name in the URL. If installing, ensure you included the /simple/ suffix if your tool requires it (though OrbitRepos usually redirects).

Metadata Errors

OrbitRepos supports both PEP 503 (HTML) and PEP 691 (JSON) metadata. If your client is very old, ensure it supports the Simple repository API.

Package Name Normalization

OrbitRepos follows PEP 503 normalization rules (e.g., Friendly-Bard is normalized to friendly-bard). Always use normalized names when manually querying the API.