What is PEP 503?
PEP 503 defines the “Simple Repository API” — the interface that Python package repositories must implement to be compatible with package installers like pip and uv. PyPI implements this API, and the specification allows anyone to host a compatible package index.
How the Simple Repository API Works
The API is intentionally minimal. A compliant repository serves two types of HTML pages:
Root index (
/simple/) — an HTML page with 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>/) — an HTML page listing downloadable files for a specific 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 # allows installers to verify download integrity.
Using Alternative Indexes
Package installers can be pointed at any PEP 503-compliant index. This is how organizations host private packages:
# 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-packageImpact
This standardization enabled the growth of private package repositories (like Artifactory, AWS CodeArtifact, and Google Artifact Registry) and alternative indexes like TestPyPI, all using the same interface that pip and uv already understand.