How uv caching works
An index marked default = true replaces PyPI for every package that is not pinned to another index. Cacheport serves the simple API that uv expects, including the JSON form uv prefers.
uv.lock stores the index each package came from. Run uv lock once after switching and commit the lockfile; versions and hashes stay identical.
- Index pages
- JSON and HTML simple API, refreshed every 5 minutes.
- Wheels
- Every platform tag cached separately.
- Python downloads
- uv python install fetches interpreters from GitHub; those are not proxied by the index.
Set it up
pyproject.toml
[[tool.uv.index]]
name = "cacheport"
url = "https://acme.cacheport.cc/pypi/simple/"
default = trueOr for a single command
export UV_DEFAULT_INDEX="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"
uv pip install -r requirements.txtFor an index named cacheport, uv reads credentials from UV_INDEX_CACHEPORT_USERNAME and UV_INDEX_CACHEPORT_PASSWORD, so the URL in the repository carries no secrets.
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:
UV_INDEX_CACHEPORT_USERNAME: ci
UV_INDEX_CACHEPORT_PASSWORD: ${{ secrets.CACHEPORT_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
with:
enable-cache: true
- run: uv sync --locked
- run: uv run pytestMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: ghcr.io/astral-sh/uv:python3.13-bookworm
variables:
UV_INDEX_CACHEPORT_USERNAME: ci
script:
- export UV_INDEX_CACHEPORT_PASSWORD="$CACHEPORT_TOKEN"
- uv sync --locked
- uv run pytestMore for GitLab CI: GitLab CI setup guide.
uv cache and Cacheport
setup-uv can persist uv's own cache between runs, keyed on the lockfile. When the key misses, uv downloads what it needs from the index, and that is where Cacheport takes over. uv also prunes its CI cache to keep it small, so a fast index matters even with the cache turned on.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.