PyPI Redirect Server

PyPI Redirect Server is a small, dependency-free Python service that acts like a PyPI Simple Repository API server. It serves packages from a local directory when they are available and redirects missing packages to a configurable upstream repository such as the official PyPI.

Features

• Serves local wheel and source distribution files through /simple/.
• Redirects cache misses to a configurable upstream repository.
• Uses only the Python standard library at runtime.
• Runs on Windows, macOS, and Linux.
• Refreshes the local package cache while the server is running.
• Logs every request routing decision to stdout.
• Serves the latest cached version by default when a project has multiple versions.
• Provides a console command and a python -m entry point.

Installation

From a checkout:

python -m pip install -e .

No runtime dependencies are installed.

Quick Start

Create a cache directory and put package files in it:

mkdir packages
python -m pip download requests -d packages

Start the server:

pypi-redirect-server --package-dir packages --host 127.0.0.1 --port 8080

Install packages through the server:

python -m pip install --index-url http://127.0.0.1:8080/simple requests

If requests exists in packages, pip downloads it from this server. If a package is not in the local cache, the server redirects pip to the configured upstream repository.

Every request writes a routing log line to stdout:

time=2026-05-28T06:56:05Z client=127.0.0.1:65503 method=GET path="/simple/demo-pkg/" status=200 action=local-index project=demo-pkg requested_version=- selected_version=2.0.0 upstream=no

Upstream Repository

The default upstream is the official PyPI:

https://pypi.org

Change it with --upstream:

pypi-redirect-server --upstream https://pypi.org/simple

The upstream can be either a site root or a Simple API root. For example, https://pypi.org and https://pypi.org/simple both work.

Package Cache Layout

The cache can be flat:

packages/
  demo_pkg-1.0.0-py3-none-any.whl
  other_project-2.1.0.tar.gz

It can also be grouped by project:

packages/
  demo-pkg/
    demo_pkg-1.0.0-py3-none-any.whl

See Package Cache for details.

Configuration

Every setting is available as a command-line flag and as an environment variable. Common examples:

pypi-redirect-server --package-dir packages --upstream https://pypi.org --port 8080

PYPI_REDIRECT_PACKAGE_DIR=packages PYPI_REDIRECT_UPSTREAM=https://pypi.org pypi-redirect-server

On PowerShell:

$env:PYPI_REDIRECT_PACKAGE_DIR = "packages"
$env:PYPI_REDIRECT_UPSTREAM = "https://pypi.org"
pypi-redirect-server

See Configuration for the full reference.

Development

Run the tests with:

python -m unittest discover -s tests

Run the server directly from the source tree after installation:

python -m pypi_redirect_server --package-dir packages

Behavior

For a request like /simple/demo/:

1. The server normalizes demo using PEP 503 rules.
2. If cached files for demo exist, it returns local links for the latest cached version.
3. If a local version selector is present, such as ?version=1.0.0 or ?minor=1.2, it returns the latest matching local files.
4. If no matching local files exist, it redirects to the configured upstream, for example https://pypi.org/simple/demo/.

Local package file URLs are served from /packages/<project>/<filename>.

Use --all-versions when you want the local Simple API page to expose every cached version and let pip do all version resolution client-side.

Pip does not send command-line version constraints such as demo==1.0.0 to a Simple API server. The ?version= and ?minor= selectors are useful for direct HTTP clients, but pip normally resolves versions from the links returned by the index page.