Replacing pip / poetry with uv — Python packaging + index setup for AI projects

pip takes 80s to install a vLLM stack, uv does it in 8s — and the lockfile is clean and reproducible. Here is the setup we ship to GPU customers.

The pitch in one line

uv is Astral's Rust-written Python package manager — pip + virtualenv + pip-tools + poetry rolled into one, 10–100× faster than pip. After using it on 5 customer projects, my consistent take: you don't have to migrate old projects, but for new ones just start with uv, no need to debate.

1. Five-minute bootstrap

# 1) install uv (it ships its own Python, no need to install one first)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) start a project
uv init my-llm && cd my-llm

# 3) add deps (auto-creates .venv, writes pyproject.toml)
uv add torch==2.5.1 vllm==0.7.2 transformers accelerate

# 4) run code (no `source activate`; uv run picks the project venv)
uv run python train.py

# 5) one-shot reproduce after a clone
uv sync          # bring env in line with uv.lock

uv.lock is a cross-platform lockfile (one file locks linux-x86_64, linux-aarch64, osx-arm64, …). Commit it and CI is happy.

2. China mirrors

Project-level — in pyproject.toml:

[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu124"
explicit = true            # only used for packages that opt in

[tool.uv.sources]
torch       = { index = "pytorch" }
torchvision = { index = "pytorch" }

explicit = true matters — the official PyTorch index only hosts torch-family wheels and is not a viable global default. Pin specific packages to it via [tool.uv.sources].

Global — ~/.config/uv/uv.toml:

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

Ad-hoc — env vars take precedence:

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/

3. China mirrors that still work in 2026

Mirror	URL	Notes
Tsinghua	`https://pypi.tuna.tsinghua.edu.cn/simple`	Most stable, recommended default
Aliyun	`https://mirrors.aliyun.com/pypi/simple/`	Fast, popular in enterprise
USTC	`https://pypi.mirrors.ustc.edu.cn/simple/`	Still maintained
Douban	`https://pypi.doubanio.com/simple/`	Unreliable, not recommended
Huawei Cloud	`https://repo.huaweicloud.com/repository/pypi/simple/`	Backup

Heads-up: HuggingFace, download.pytorch.org, xformers, etc. are not on China mirrors. Add them as separate [[tool.uv.index]] entries pointing to the upstream or to your own reverse proxy.

4. Coexisting with legacy pip projects

Old repo with only requirements.txt, don't want to restructure?

uv venv                                     # create .venv
uv pip install -r requirements.txt          # old syntax, new speed
uv pip compile requirements.in -o requirements.txt   # lockfile

This is uv's pip-compat mode — same behaviour as pip, just much faster. No pyproject.toml required.

5. uv inside CI / Docker

Dockerfile excerpt:

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev          # strict: install must match lock

COPY . .
CMD ["uv", "run", "python", "-m", "app"]

--frozen guarantees CI / prod installs match the lockfile bit-for-bit; --no-dev excludes dev-only deps.

6. Numbers from a real migration

A customer project (vLLM + LangChain + Streamlit), 180 direct deps, ~1200 transitive:

Operation	pip + venv	uv
Cold install (no cache)	3m20s	18s
Warm install (cache hit)	1m05s	1.1s
Lockfile size	none / pip-tools 12 KB	uv.lock 38 KB (multi-platform)
Cross-machine reproducibility	hit-or-miss	`uv sync` is deterministic

Migration cost = write one pyproject.toml + run uv lock once. Easy sell to any team.