cacheport

Ecosystem · Python

PyPI cache for pip in CI

Cacheport serves a standard simple index that pip already understands. Set one environment variable and every wheel after the first download comes from a cache in your region.

CP-PIPManifest
Upstream
pypi.org and files.pythonhosted.org
Endpoint
https://acme.cacheport.cc/pypi/simple/
Protocol
Simple repository API (PEP 503, PEP 691 JSON)
Config
PIP_INDEX_URL or pip.conf
Hash checking
Works, files are byte-identical
Files
Wheels and sdists cached forever

How pip caching works

pip finds packages through an index: it asks for /simple/<project>/, gets a list of files with their hashes, then downloads the one that fits the interpreter and platform. Cacheport caches the index pages for a few minutes and the files themselves for good.

Because every file is served exactly as PyPI published it, --require-hashes and the hashes in a requirements.txt compiled with pip-tools still match.

What gets cached
Index pages
Refreshed every 5 minutes, last good copy if PyPI is unreachable.
Wheels
Every platform tag you request is cached separately, so arm64 and x86_64 runners both hit.
Source distributions
Cached as published. Builds still happen on your runner.

Set it up

Environment variable (recommended for CI)

shell
export PIP_INDEX_URL="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"
pip install -r requirements.txt

pip.conf for laptops

~/.config/pip/pip.conf
[global]
index-url = https://acme.cacheport.cc/pypi/simple/
# pip asks keyring or ~/.netrc for the token

pip does not expand environment variables inside pip.conf, so in CI pass the URL through PIP_INDEX_URL, which your shell expands. Mask the variable in your CI settings.

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:
      PIP_INDEX_URL: https://ci:${{ secrets.CACHEPORT_TOKEN }}@acme.cacheport.cc/pypi/simple/
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
test:
  image: python:3.13
  script:
    - export PIP_INDEX_URL="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"
    - pip install -r requirements.txt
    - pytest

More for GitLab CI: GitLab CI setup guide.

Extra indexes and dependency confusion

--extra-index-url makes pip look at several indexes and pick the highest version from any of them, which is how dependency confusion attacks work. Cacheport removes the need for it: add your private index as an upstream of the workspace, and Cacheport answers for private names from that upstream only, never from PyPI.

Faster wheels for big packages

Scientific packages ship large wheels: a single build of a machine learning framework can be hundreds of megabytes. These are exactly the files that time out from shared runners. Served from a regional cache they download at local network speed.

Troubleshooting

Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.

Questions

Does Cacheport build wheels for me?

No. It caches what PyPI publishes. If a project only ships an sdist, pip builds it on your runner as before.

Does it support the JSON simple API?

Yes. Cacheport serves both the HTML and the JSON forms of the simple API, and pip picks the one it prefers.

Can I use it with pip-tools or pip download?

Yes. Anything that reads PIP_INDEX_URL or takes --index-url works.

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.