pypi-mirror / package pull-through cache

This host proxies and caches packages from pypi.org. Point pip, Poetry, or uv here to speed up installs and cut outbound rate-limit hits. Replace mirror.example.com below with this server's actual hostname.

01 — GLOBAL PIP CONFIG

Set the index for your user

Write the mirror into pip's user config so every pip install uses it by default.

shell

pip config set global.index-url https://mirror.example.com/simple/

# confirm it took
pip config get global.index-url

This writes to ~/.config/pip/pip.conf (Linux/macOS) or %APPDATA%\pip\pip.ini (Windows).

02 — PER-PROJECT (RECOMMENDED)

pip.conf / pip.ini in the repo

Scope the mirror to a single project — safer for teams and reproducible in CI.

pip.conf

[global]
index-url = https://mirror.example.com/simple/
trusted-host = mirror.example.com

Or pass it inline without any config file: pip install -i https://mirror.example.com/simple/ requests

03 — POETRY / UV

pyproject.toml

[[tool.poetry.source]]
name = "mirror"
url = "https://mirror.example.com/simple/"
priority = "primary"

shell

export UV_INDEX_URL=https://mirror.example.com/simple/

04 — CI/CD

Environment variable override

No repo changes needed — set this in your pipeline's environment.

shell

export PIP_INDEX_URL=https://mirror.example.com/simple/

05 — VERIFY

Confirm installs are going through the mirror

shell

pip config get global.index-url
curl -s https://mirror.example.com/simple/ -o /dev/null -w "%{http_code}\n"

# install something and time it
time pip install requests --no-cache-dir

Check	Expected result
`pip config get global.index-url`	Prints `https://mirror.example.com/simple/`
`GET /simple/`	`200` — mirror is reachable
First install of a package	Slower — cache miss, fetched from upstream and stored
Repeat install	Fast — served from local cache

06 — NOTES

Pull-through, not a full copy. This mirror implements the PyPI simple index protocol and caches packages as they're requested — it doesn't proactively sync the entire PyPI catalog. The first install of any given package/version is still fetched from pypi.org.

twine upload still goes straight to the real index — this mirror only accelerates installs. If it's served over plain HTTP internally, add its host to trusted-host as shown above, or terminate TLS in front of it.