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. |
Create the repositories
Section titled “Create the repositories”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/ |
Install packages
Section titled “Install packages”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.
[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:
export PIP_INDEX_URL="https://__token__:$ENTREPOT_TOKEN@entrepot.example.com/repository/pypi-group/simple/"One-off, for an anonymously readable repository:
pip install --index-url https://entrepot.example.com/repository/pypi-group/simple/ requests[[tool.uv.index]]name = "entrepot"url = "https://entrepot.example.com/repository/pypi-group/simple/"default = trueexport UV_INDEX_ENTREPOT_USERNAME=tokenexport UV_INDEX_ENTREPOT_PASSWORD="$ENTREPOT_TOKEN"uv sync
# or ad hocuv pip install --index-url "https://__token__:$ENTREPOT_TOKEN@entrepot.example.com/repository/pypi-group/simple/" mypkgpoetry source add --priority=primary entrepot https://entrepot.example.com/repository/pypi-group/simple/poetry config http-basic.entrepot token "$ENTREPOT_TOKEN"poetry install--index-url https://__token__:${ENTREPOT_TOKEN}@entrepot.example.com/repository/pypi-group/simple/requests==2.32.3pip expands ${VAR} references in requirements files, so the token itself
is never committed.
Publish
Section titled “Publish”python -m buildtwine upload --repository-url https://entrepot.example.com/repository/pypi-internal/ \ -u __token__ -p "$ENTREPOT_TOKEN" dist/*Or with ~/.pypirc:
[distutils]index-servers = entrepot
[entrepot]repository = https://entrepot.example.com/repository/pypi-internal/username = __token__password = <TOKEN>twine upload -r entrepot dist/*uv builduv publish --publish-url https://entrepot.example.com/repository/pypi-internal/ \ --username token --password "$ENTREPOT_TOKEN"poetry config repositories.entrepot-internal https://entrepot.example.com/repository/pypi-internal/poetry publish --build -r entrepot-internal -u token -p "$ENTREPOT_TOKEN"curl -fsS -H "Authorization: Bearer $ENTREPOT_TOKEN" \ -F file=@dist/mypkg-1.0.0-py3-none-any.whl \ https://entrepot.example.com/api/v1/repositories/pypi-internal/uploadThe project name and version are read from the file name.
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.
From GitLab CI
Section titled “From GitLab CI”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.
Delete
Section titled “Delete”# 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 projectcurl -X DELETE -H "Authorization: Bearer $ENTREPOT_TOKEN" \ https://entrepot.example.com/repository/pypi-proxy/simple/requestsTroubleshooting
Section titled “Troubleshooting”- pip shows
401or 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
preferHostedenabled 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.