uv: Fast Python Package & Project Management

Q: Is uv a replacement for pip?

Yes, for most uses. Its uv pip interface is largely compatible with pip's commands, and its project commands go further with lockfiles and environment management.

Q: Does uv work on Windows?

Yes. uv supports Windows, macOS, and Linux, and uv.lock is designed to be universal across platforms.

uv

uv is a Python package and project manager from Astral, written in Rust. It replaces a whole toolbox — pip, pip-tools, virtualenv, pipx, pyenv, and much of what Poetry or PDM do — with one fast binary. Installs that took minutes with pip often take seconds, because uv resolves dependencies in parallel, caches aggressively, and links packages from a global cache instead of copying them.

Speed is what people notice first; consistency is why teams stay. uv manages the Python interpreter, the virtual environment, dependencies, a cross-platform lockfile, scripts, and command-line tools with one set of commands, so "works on my machine" problems in Python projects largely disappear.

TL;DR

Projects use pyproject.toml for dependencies and uv.lock as a universal, cross-platform lockfile.
uv add, uv remove, uv sync, and uv run manage the environment automatically — no manual activation needed.
uv python install and .python-version manage interpreters; no separate pyenv.
uvx runs command-line tools in isolated environments, replacing pipx.
Inline script metadata (PEP 723) lets single-file scripts declare their own dependencies.
uv pip offers a pip-compatible interface for existing workflows, including uv pip compile for requirements files.

Quick Example

Start a service, pin Python, add dependencies, and run tests:

The resulting pyproject.toml:

A colleague clones the repository and runs uv sync — uv installs the pinned Python version if needed, creates .venv, and installs exactly what uv.lock records.

Core Concepts

Projects and the Lockfile

A uv project is defined by pyproject.toml. uv.lock records the full resolution for every supported platform and Python version at once, so the same lockfile works on macOS laptops, Windows machines, and Linux CI runners. uv run and uv sync check that the environment matches the lockfile before running anything.

Dependency Groups

Development-only dependencies go in dependency groups (PEP 735) such as dev, test, or docs. uv sync installs the dev group by default; --no-dev and --group control the rest. Optional features for library users still use [project.optional-dependencies].

Python Versions

uv downloads and manages standalone Python builds. uv python install 3.12 3.13 installs versions, uv python pin writes .python-version, and projects automatically use a compatible interpreter. CI and containers can use the same mechanism instead of OS packages.

Tools and Scripts

uvx ruff check . runs a tool in a temporary, cached environment; uv tool install installs it persistently.
Inline script metadata puts dependencies at the top of a single-file script:

uv run check_status.py creates an environment with those packages and runs the script. uv add --script check_status.py httpx edits the metadata for you.

The pip Interface

For projects not ready to adopt uv's project model, uv pip install, uv pip sync, uv venv, and uv pip compile requirements.in -o requirements.txt work as faster replacements for pip, virtualenv, and pip-tools with familiar arguments.

Workspaces

Like Cargo workspaces, a uv workspace groups several packages in one repository with a single lockfile, declared in the root pyproject.toml under [tool.uv.workspace]. Members depend on each other as editable installs. See Monorepos.

uv in Docker and CI

A container image that installs dependencies in a cached layer before copying source code:

In CI, uv sync --locked fails if uv.lock does not match pyproject.toml, catching forgotten lock updates; cache uv's cache directory between runs. See Docker Multi-Stage Builds.

Migrating to uv

If other tools need a requirements file, uv export --format requirements-txt generates one from the lockfile.

Best Practices

Commit uv.lock and Use --locked in CI

The lockfile is the source of truth for reproducible installs. Fail CI builds when it is stale.

Use uv run Instead of Activating Environments

uv run guarantees the environment matches the lockfile before every command, which removes a whole class of "forgot to reinstall" problems.

Upgrade Deliberately

Upgrade one package with uv lock --upgrade-package <name> or everything with uv lock --upgrade, and review the lockfile diff like code. See Software Supply Chain Security.

Pin the uv Version

Pin uv in Docker images and CI setup actions, and set required-version in configuration if teams must agree on a minimum.

Common Mistakes

Mixing pip Into a uv Project

Copying Source Before Dependencies in Docker

Ignoring the Lockfile in CI

FAQ

What is uv?

A fast Python package and project manager written in Rust by Astral. It manages dependencies, lockfiles, virtual environments, Python versions, tools, and scripts, replacing pip, pip-tools, virtualenv, pipx, and pyenv for most workflows.

Is uv a replacement for pip?

Yes, for most uses. Its uv pip interface is largely compatible with pip's commands, and its project commands go further with lockfiles and environment management.

Is uv better than Poetry?

Both manage projects with lockfiles. uv is much faster, also manages Python versions and tools, and uses standard pyproject.toml metadata throughout. Poetry has a long track record and its own plugin ecosystem; many teams have migrated to uv for speed and simplicity.

Does uv work on Windows?

Yes. uv supports Windows, macOS, and Linux, and uv.lock is designed to be universal across platforms.

How do I run a script with dependencies without a project?

Add PEP 723 inline metadata listing dependencies at the top of the script, then run it with uv run script.py. uv creates a cached environment with those packages automatically.

uv