PyTail

pytail is a small PyPI caching proxy. It exposes a Python Simple Repository API endpoint, fetches packages from upstream on demand, and keeps downloaded files in a local cache.

It is useful when you want faster repeated installs, a simple shared package cache, or a local endpoint for PyPI and PyTorch wheel indexes.

Features

• PyPI-compatible /simple/ endpoint for pip and uv
• lazy caching of project pages and package files
• optional cache size limit with least-recently-used cleanup
• PyTorch wheel index proxy under /pytorch-wheels/
• HTML and JSON Simple API responses

Install

Install from PyPI:

pip install pytail

Or install from source:

cargo install --path .

Run

After installation:

pytail \
  --bind 127.0.0.1:3141 \
  --cache-dir .cache/pytail

From a source checkout:

cargo run -- \
  --bind 127.0.0.1:3141 \
  --cache-dir .cache/pytail

Then use it as the package index:

uv pip install --index-url http://127.0.0.1:3141/simple/ requests
pip install --index-url http://127.0.0.1:3141/simple/ requests

Open the local index in a browser:

http://127.0.0.1:3141/simple/

PyTorch Wheels

PyTorch wheel indexes are available under /pytorch-wheels/.

For example, this upstream command:

pip install torch --index-url https://download.pytorch.org/whl/cu126

can use the local cache instead:

pip install torch --index-url http://127.0.0.1:3141/pytorch-wheels/cu126

If a package needs both PyTorch wheels and normal PyPI packages:

pip install torch \
  --index-url http://127.0.0.1:3141/pytorch-wheels/cu126 \
  --extra-index-url http://127.0.0.1:3141/simple/

Flat wheel mirrors, such as the Aliyun PyTorch mirror, can be converted into the same project-based Simple API. Start PyTail with the mirror root and enable flat-index mode:

pytail \
  --torch-url https://mirrors.aliyun.com/pytorch-wheels/ \
  --torch-flat-index

Clients continue to use the normal local project index. For example:

pip install torch \
  --index-url http://127.0.0.1:3141/pytorch-wheels/cu128

Options

Common options:

• --bind: listen address, default 127.0.0.1:3141
• --cache-dir: cache directory, default .cache/pytail
• --cache-max-size: max file cache size, default 0 for unlimited; examples: 512MiB, 2G, 10GB
• --upstream-base-url: PyPI-compatible upstream, default https://pypi.org
• --torch-url: PyTorch wheel upstream, default https://download.pytorch.org/whl/
• --torch-flat-index: treat each PyTorch channel URL as a flat --find-links page and expose it as a project-based Simple API
• --project-cache-ttl-secs: project page refresh interval, default 900
• --request-timeout-secs: upstream request timeout, default 15
• --stats-interval-secs: stats log and trend sampling interval, default 3600; set to 0 to disable
• --verbose: enable operational debug logs; use RUST_LOG=pytail=trace for per-request and cache-hit details

Build

Build the Rust binary:

cargo build --release

Build a Python wheel with maturin:

maturin build --release

The wheel installs the pytail command.