uv: one fast tool for Python packages, virtual environments and versions

Setting up a Python project used to mean juggling several tools: one to install Python versions, one to create a virtual environment, pip to install packages, and something else to lock versions. uv, from Astral (the team behind Ruff), does all of that in one binary written in Rust, and it is fast enough that installs which took a minute often finish in seconds.

Install

pipx install uv        # or: pip install uv
uv --version

The project also publishes standalone installers and packages for Homebrew, WinGet and others; see the official documentation.

The project workflow

uv manages projects through the standard pyproject.toml plus a lock file.

uv init my-service           # creates pyproject.toml and a starter module
cd my-service
uv add fastapi "httpx>=0.27" # adds dependencies and updates uv.lock
uv add --dev pytest ruff     # development-only dependencies
uv run pytest                # runs inside the project's environment

A few things happen without you asking:

• A virtual environment (.venv) is created and kept in sync with the lock file.
• uv.lock records exact versions for every platform, so teammates and CI get the same dependency tree.
• uv run makes sure the environment matches the lock file before running your command, so "works on my machine" problems from stale environments mostly disappear.

On a fresh checkout, one command reproduces the environment:

uv sync

Managing Python versions

uv can download and manage Python itself:

uv python install 3.12
uv python pin 3.12       # writes .python-version for the project

This removes the need for a separate version manager on most machines and in CI.

Drop-in pip commands

If you're not ready to change your project layout, uv offers a pip-compatible interface that is simply faster:

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt   # like pip-tools

This is an easy way to try uv in an existing project without touching anything else.

Running tools without installing them

uvx runs a command-line tool in a temporary, cached environment:

uvx ruff check .
uvx httpie https://example.com

It's handy for one-off tools you don't want in your project's dependencies.

In CI

A typical GitHub Actions job becomes shorter and faster:

- uses: astral-sh/setup-uv@v5
- run: uv sync --locked
- run: uv run pytest -q

--locked fails the build if uv.lock is out of date with pyproject.toml, which catches "forgot to commit the lock file" mistakes.

When to switch, and when not to

Good reasons to adopt uv:

• Slow dependency installs in CI or Docker builds.
• A team that keeps hitting environment drift.
• Several projects needing different Python versions.

Things to check first:

• If your organisation relies on Conda for non-Python dependencies (CUDA, GDAL and similar), uv doesn't replace that.
• Very old tooling that expects setup.py-only projects may need updating to pyproject.toml.
• Pin a uv version in CI so a tool upgrade doesn't change behaviour unexpectedly.

Verdict

For new Python projects, uv is an easy recommendation: one tool, standard pyproject.toml, reproducible locks and very fast installs. For existing projects, start with uv pip install in CI, enjoy the speed-up, and move to the full project workflow when it suits you.