uv pip sync: Managing Reproducible Python Environments

We often see “works on my machine” frustrations. uv pip sync provides exact, reproducible Python environments that sync precisely to your requirements.txt, removing any extra packages. It works on system Python without a virtual‑environment overhead, which is useful for global tools and scripts. You might wonder why not just use pip; the answer lies in speed and reproducibility.

Why Use uv pip sync

pip install -r requirements.txt installs listed packages but leaves previously installed “orphan” packages untouched, which can reduce reproducibility. uv pip sync uninstalls those extras, ensuring the environment matches the requirements exactly.

Key features include:

• Speed: Rust-based resolver and installer, typically faster than pip.
• Precision: Matches requirements exactly—no extras, no missing.
• No venv required: Syncs system Python directly for low-overhead use cases.
• Lockfile compatible: Works with uv pip compile for pinned dependencies.

It offers a practical alternative to pip-tools (replacing pip-compile and pip-sync), with speed comparable to Poetry for simpler workflows.

Installing uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

The installer typically places uv in ~/.cargo/bin; add this to your PATH if needed and source your shell profile (e.g., source ~/.bashrc). Verify the installation worked with the command above—you should see output like “uv 0.4.9”. Other installation methods: - macOS: brew install uv - Windows: winget install -e --id astral-sh.uv - Cargo: cargo install uv - PyPI: pip install uv (uses Python interpreter, standalone preferred for speed)

Basic Usage

Create requirements.txt:

requests==2.32.3
numpy>=1.26.0

Sync:

uv pip sync requirements.txt

Output:

Resolved 15 packages in 5ms
Installed 5 packages in 20ms (from cache)
+ requests==2.32.3
+ numpy==1.26.4
...

uv pip sync removes previously installed packages not in requirements.txt (shown as - in output) and installs new ones (+). This ensures reproducibility. Verify with: bash
$ uv pip list
 The listed packages should match your requirements (resolved versions may vary slightly by platform).

Lockfiles with uv pip compile

For true reproducibility:

Tip: Use uv pip compile to generate a fully pinned requirements.txt that captures all transitive dependencies.

# Generate pinned requirements.txt
uv pip compile requirements.in -o requirements.txt

# Sync anywhere
uv pip sync requirements.txt

requirements.in uses loose specs; compile pins them platform-independently, ensuring identical environments everywhere. Use uv pip compile --upgrade to update when deps change; commit the lockfile to version control.

Syncing System Python Directly

For scripts or global tools, sync directly to system Python:

# On system Python 3.12
uv pip sync --python /usr/bin/python3.12 requirements.txt

Or activate base python—no .venv bloat. uv’s cache deduplicates, minimal disk/IO.

Compare:

Tool	Venv Needed?	Sync Speed	Removes Extras?
pip install -r	Usually	Baseline	No
uv pip sync	Optional	Faster	Yes
Poetry install	Yes	Medium	Yes

Performance: uv pip sync vs pip

Test setup: mid-range laptop, project with 100+ deps (FastAPI-like), cold cache.

pip install -r: 45s resolve + 120s install
uv pip sync: 50ms resolve + 300ms install (8s cached)

Subsequent runs use cache for near-instant syncs. Results vary by hardware, network, disk.

Advanced Usage

# Only dev deps
uv pip sync requirements-dev.txt

# Universal install (no platform wheels)
uv pip compile --universal requirements.in

# Python version override
uv pip sync --python 3.13 requirements.txt

uv integrates with version managers like mise or asdf (see pyenv to mise migration guide).

Migrating from Other Tools

• pip-tools: Replace pip-compile/pip-sync with uv pip compile/sync.
• Poetry: Export poetry export -f requirements.txt, then uv sync.

Common Pitfalls & Fixes

• Permission errors: Use --user or sudo (avoid!).
• System deps: Pre-install via apt/brew.
• Verify: uv pip list matches requirements.

Conclusion

uv pip sync delivers reproducible, efficient dependency management—especially without venv overhead for tools. With uv pip compile, it supports consistent CI/CD pipelines. Weigh it against pip-tools or Poetry; uv shines for speed in simpler setups.

Related: pip/uv/Poetry comparison, Mise benchmarks.