Skip to content

PyPI

Entrepot implements the PyPI simple repository API (PEP 503 HTML and PEP 691 JSON) plus the legacy upload API used by twine. It serves PEP 658 metadata files, so pip and uv resolve dependencies without downloading whole wheels.

Kind Behaviour
hosted Accepts twine upload (and anything that speaks the legacy upload API).
proxy Caches the project pages and files of pypi.org or another simple index, verifying each file’s sha256 against the upstream index before caching it.
group Merges the project pages of its members — the first member wins for a given filename — and serves files from the first member that has them. With preferHosted (default), proxies never contribute files for a project a hosted member has.
Terminal window
api -X POST $E/api/v1/repositories -d '{"name":"pypi-proxy","format":"pypi","kind":"proxy","blobStore":"default","proxy":{"remoteUrl":"https://pypi.org"}}'
api -X POST $E/api/v1/repositories -d '{"name":"pypi-internal","format":"pypi","kind":"hosted","blobStore":"default"}'
api -X POST $E/api/v1/repositories -d '{"name":"pypi-group","format":"pypi","kind":"group","blobStore":"default","group":{"members":["pypi-internal","pypi-proxy"]}}'

proxy.remoteUrl can be a server root (https://pypi.org, /simple is appended) or a simple index itself, such as another Entrepot’s https://other.example.com/repository/pypi/simple.

Use URL
Index (pip, uv, poetry) https://entrepot.example.com/repository/pypi-group/simple/
Upload (twine, uv publish, poetry publish) https://entrepot.example.com/repository/pypi-internal/

Credentials can be embedded in the index URL; any username works and the password is the token. File links in the index are relative, so the same credentials are used for downloads.

~/.config/pip/pip.conf
[global]
index-url = https://__token__:<TOKEN>@entrepot.example.com/repository/pypi-group/simple/

Or keep the token out of files with an environment variable, which pip reads like the config option:

Terminal window
export PIP_INDEX_URL="https://__token__:$ENTREPOT_TOKEN@entrepot.example.com/repository/pypi-group/simple/"

One-off, for an anonymously readable repository:

Terminal window
pip install --index-url https://entrepot.example.com/repository/pypi-group/simple/ requests
Terminal window
python -m build
twine upload --repository-url https://entrepot.example.com/repository/pypi-internal/ \
-u __token__ -p "$ENTREPOT_TOKEN" dist/*

Or with ~/.pypirc:

~/.pypirc
[distutils]
index-servers = entrepot
[entrepot]
repository = https://entrepot.example.com/repository/pypi-internal/
username = __token__
password = <TOKEN>
Terminal window
twine upload -r entrepot dist/*

Project names are normalised per PEP 503 (My_Package → my-package). Uploading a file that already exists returns 409 unless hosted.allowRedeploy is enabled. Distributions are limited to 2 GiB.

publish:
image: python:3.12
id_tokens:
ENTREPOT_ID_TOKEN:
aud: https://entrepot.example.com
script:
- pip install build twine
- python -m build
- twine upload --repository-url https://entrepot.example.com/repository/pypi-internal/ -u gitlab-ci -p "$ENTREPOT_ID_TOKEN" dist/*

See GitLab CI for the trust policy and role binding the job needs.

Terminal window
# a single file, a version, or a whole project (hosted, or cached proxy content)
curl -X DELETE -H "Authorization: Bearer $ENTREPOT_TOKEN" \
https://entrepot.example.com/repository/pypi-internal/packages/mypkg/1.0.0/
# drop a proxy's cached upstream index for a project
curl -X DELETE -H "Authorization: Bearer $ENTREPOT_TOKEN" \
https://entrepot.example.com/repository/pypi-proxy/simple/requests
  • pip shows 401 or keeps prompting for a password — the repository is not anonymously readable and no credentials were sent. Embed them in the index URL (https://__token__:<TOKEN>@…) or use a keyring.
  • A new upstream release isn’t visible — the proxy caches project pages for proxy.metadataTtlSeconds (default 3600). Lower it, or delete the cached page (DELETE …/simple/<project>).
  • An internal project resolves to the public one — check the group still has preferHosted enabled and that the hosted repository is a member. Add a routing rule for your prefixes.
  • 403 … waive or fix to download — the file is quarantined by the repository’s scan policy.