cacheport

Ecosystem · Python

PyPI cache for Poetry in CI

Poetry resolves and installs from package sources listed in pyproject.toml. Add Cacheport as the primary source and Poetry stops reaching out to PyPI for anything already in your cache.

CP-POETRYManifest
Upstream
pypi.org
Endpoint
https://acme.cacheport.cc/pypi/simple/
Config
[[tool.poetry.source]] in pyproject.toml
Credentials
POETRY_HTTP_BASIC_CACHEPORT_*
Lockfile
poetry.lock records the source
Files
Wheels and sdists cached forever

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.

What gets cached
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

shell
poetry source add --priority=primary cacheport https://acme.cacheport.cc/pypi/simple/
poetry lock

Resulting pyproject.toml

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

.github/workflows/ci.yml
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 pytest

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
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 pytest

More 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.

Questions

Do I need to keep PyPI as a source?

No. With Cacheport as the primary source, Poetry does not need PyPI listed at all.

Why did poetry.lock change?

Poetry records which source each package came from. The versions and hashes stay the same; only the source entries change.

Does it work with Poetry 2?

Yes. Source priorities work the same way in Poetry 1.8 and 2.x.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.