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.
- 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)
export PIP_INDEX_URL="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"
pip install -r requirements.txtpip.conf for laptops
[global]
index-url = https://acme.cacheport.cc/pypi/simple/
# pip asks keyring or ~/.netrc for the tokenpip 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
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: pytestMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: python:3.13
script:
- export PIP_INDEX_URL="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"
- pip install -r requirements.txt
- pytestMore 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.