PyPI cache · private index · one binary

Your packages, served from next door.

velodex is a PyPI-compatible read-through cache and private package index in a single Rust binary. Point pip, uv, or twine at it; the only change a client needs is the index URL. First install runs at upstream speed while the cache fills, every one after comes from your own disk.

Get started Source on GitHub

$ velodex serve
velodex listening on 127.0.0.1:4433 · 3 indexes
$ uv pip install --index-url \
    http://127.0.0.1:4433/root/pypi/simple/ requests
Installed 5 packages in 41ms

1binary, no database or broker

0.7swarm uv pip install pandas polars 100%line & function coverage

PEP 691 · 658 · 700 · 592 modern index protocols

pip · uv · twine verified end to end

Read-through cache Proxies pypi.org or any PEP 503/691 index. A cache miss streams upstream bytes to the client while writing them aside, so the first install pays no penalty; every later one comes from disk. Each artifact verifies against its sha256 and is stored once, content-addressed, however many projects pull it.
Private packages that shadow upstream twine and uv publish upload over the standard API into virtual indexes, where your utils beats the utils someone registered on pypi.org. One index-url, no --extra-index-url, no dependency confusion.
Modern resolver protocols PEP 691 JSON with PEP 503 HTML fallback, PEP 700 fields, and the PEP 658/714 .metadata fast path that lets pip and uv resolve from kilobytes of metadata instead of whole wheels.
Honest freshness Upstream Cache-Control decides how long a page serves from cache; a background sweep catches upstream changes even for pages nobody is requesting; outages degrade to stale-but-working.
Built to operate One TOML file, Prometheus metrics, per-file usage drill-down, structured logs, a live web UI, and a data directory you can back up with cp. No JVM, no database server, idle RAM in the tens of MB.
Proven with real clients The test suite drives actual pip, uv, and twine against a live velodex, holds 100% line and function coverage, and the performance numbers come with the exact commands that produced them.

Documentation

Tutorials

Learning-oriented lessons: install velodex and take it from zero to serving and hosting packages.

How-to guides

Task-oriented recipes: proxy a private mirror, compose overlays, publish, yank, and delete.

Reference

Information-oriented specifications: configuration keys, HTTP endpoints, CLI flags, and metrics.

Explanation

Understanding-oriented discussion: the architecture, the index model, and the standards velodex speaks.