What is PEP 503?
PEP 503 defines the “Simple Repository API,” the protocol that package repositories implement to work with installers like pip and uv. PyPI implements this API; any organization can run a compatible private index without custom installer support.
How the Simple Repository API works
The API is intentionally minimal. A compliant repository serves two HTML pages:
-
Root index (
/simple/), listing links to each available project:<a href="/simple/requests/">requests</a> <a href="/simple/flask/">flask</a> <a href="/simple/numpy/">numpy</a> -
Project page (
/simple/<project>/), listing downloadable files for that package:<a href="requests-2.31.0.tar.gz#sha256=abc123...">requests-2.31.0.tar.gz</a> <a href="requests-2.31.0-py3-none-any.whl#sha256=def456...">requests-2.31.0-py3-none-any.whl</a>
The hash fragment after # lets installers verify download integrity without a separate request.
Configure an alternative index
Point pip or uv at any PEP 503-compliant server:
# With pip
pip install --index-url https://my-company.example.com/simple/ my-package
# With uv
uv pip install --index-url https://my-company.example.com/simple/ my-packageFor uv projects, declare the index in pyproject.toml:
[[tool.uv.index]]
name = "private"
url = "https://my-company.example.com/simple"What PEP 503 made possible
Private registry products (Artifactory, AWS CodeArtifact, Google Artifact Registry) and alternative indexes like TestPyPI all implement the same interface. Before PEP 503, each installer required its own workaround to fetch packages from non-PyPI sources.