How Poetry caching works
A source with priority = "primary" replaces PyPI as the place Poetry looks first. Cacheport answers with the same files PyPI would serve, so hashes in poetry.lock keep matching.
Poetry writes the source of each package into poetry.lock. After adding the Cacheport source, run poetry lock once and commit the result so every machine uses the same source.
- Index pages
- Refreshed every 5 minutes, last good copy on upstream failure.
- Wheels and sdists
- Cached forever, shared with pip and uv jobs.
- Private packages
- Served from your private upstream through the same source.
Set it up
Add the source
poetry source add --priority=primary cacheport https://acme.cacheport.cc/pypi/simple/
poetry lockResulting pyproject.toml
[[tool.poetry.source]]
name = "cacheport"
url = "https://acme.cacheport.cc/pypi/simple/"
priority = "primary"Poetry reads credentials for a source named cacheport from POETRY_HTTP_BASIC_CACHEPORT_USERNAME and POETRY_HTTP_BASIC_CACHEPORT_PASSWORD. Set the password to your token in CI.
Use it in CI
Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.
GitHub Actions
jobs:
test:
runs-on: ubuntu-latest
env:
POETRY_HTTP_BASIC_CACHEPORT_USERNAME: ci
POETRY_HTTP_BASIC_CACHEPORT_PASSWORD: ${{ secrets.CACHEPORT_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.13"
- run: pipx install poetry
- run: poetry install --no-interaction
- run: poetry run pytestMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: python:3.13
variables:
POETRY_HTTP_BASIC_CACHEPORT_USERNAME: ci
script:
- export POETRY_HTTP_BASIC_CACHEPORT_PASSWORD="$CACHEPORT_TOKEN"
- pip install poetry
- poetry install --no-interaction
- poetry run pytestMore for GitLab CI: GitLab CI setup guide.
One source instead of several
Projects with private packages often list PyPI and a private index as separate sources, and then fight with source priorities. Add the private index as an upstream of your Cacheport workspace instead. Poetry sees one primary source; Cacheport routes private names to the private upstream and everything else to PyPI.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.