cacheport

Ecosystem · Python

PyPI cache for uv in CI

uv resolves dependencies in milliseconds; the slow part is downloading. Set Cacheport as the default index and the downloads come from a cache next to your runners.

CP-UVManifest
Upstream
pypi.org
Endpoint
https://acme.cacheport.cc/pypi/simple/
Config
[[tool.uv.index]] with default = true
Credentials
UV_INDEX_CACHEPORT_USERNAME / _PASSWORD
Lockfile
uv.lock records the index URL
Files
Wheels and sdists cached forever

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.

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

pyproject.toml
[[tool.uv.index]]
name = "cacheport"
url = "https://acme.cacheport.cc/pypi/simple/"
default = true

Or for a single command

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

For 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

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

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

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

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

Questions

Does uv pip work too?

Yes. uv pip reads the same index settings, or UV_DEFAULT_INDEX for one-off commands.

Can I pin some packages to a private index?

Yes, with [tool.uv.sources]. Or add the private index as an upstream of your workspace and keep a single index.

Why did uv.lock change after switching?

uv records the index URL per package. Versions and hashes are the same as before.

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.