What Is uv? The Python Package Manager Explained

uv is a fast Python package and project manager from Astral. What it does, how to install it, the commands you will use, and how it compares to pip.

uv is a single, fast tool that replaces much of the usual Python toolchain: pip, virtualenv, pyenv, pipx and pip-tools. It is written in Rust by Astral, the company behind Ruff, and covers installing packages, creating environments, managing Python versions, running scripts and tools, and locking dependencies.

What uv replaces

The uv documentation describes it as a single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv and more.

Install it

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Windows (WinGet)
winget install --id=astral-sh.uv -e

The documentation also lists Homebrew (brew install uv) and PyPI. For PyPI it recommends installing uv into an isolated environment, for example with pipx install uv, though pip install uv also works.

The commands you will actually use

uv init my-app            # create a project
cd my-app
uv add httpx              # add a dependency
uv add --dev pytest       # add a development dependency
uv run my-app             # run the project's command
uv run pytest             # run any tool inside the project environment
uv sync                   # make the environment match the lockfile
uv python install 3.14    # download a Python version
uvx ruff check .          # run a tool without installing it

What these do, as checked with uv 0.13.7:

• uv init my-app creates pyproject.toml, README.md, .python-version and src/my_app/__init__.py, with a build system and a my-app command, so uv run my-app prints Hello from my-app!. There is no main.py: since uv 0.12 a new project has a build system and a src/ layout by default. Use uv init --no-package for the simpler layout with a main.py.
• uv add httpx adds httpx>=0.28.1 (the current version when checked) to dependencies in pyproject.toml, creates .venv and writes uv.lock.
• uv add --dev pytest puts pytest in a [dependency-groups] table under dev, not in dependencies.
• uv run pytest runs pytest from the project environment. With no tests it reports no tests ran.
• uvx ruff check . is shorthand for uv tool run ruff check .. The tool runs in a cached, isolated environment and is not installed permanently.

uv.lock records the exact versions resolved. The documentation says it should be checked into version control so installs are consistent and reproducible. For the file format, see pyproject.toml explained.

Scripts with their own dependencies

uv can run a single file with inline dependency metadata, so a script needs no project around it:

uv add --script example.py httpx
uv run example.py

uv add --script writes a metadata block at the top of the file, and uv run builds a temporary environment from it:

# /// script
# requires-python = ">=3.14"
# dependencies = [
#     "httpx>=0.28.1",
# ]
# ///
import httpx

print("httpx", httpx.__version__)

Running it prints httpx 0.28.1.

Installing command-line tools

uv tool install ruff      # install into an isolated environment
uv tool list              # show installed tools
uv tool upgrade --all     # upgrade them

The ruff command is then on your PATH if uv’s tool directory is. uv prints a warning with the fix when it is not, or you can run uv tool update-shell. See pipx vs uv tool for how this compares with pipx.

Why it is fast

Astral says uv is 10 to 100 times faster than pip. The figure links to the project’s benchmark page, which compares tools on installing and resolving the dependencies in Trio’s docs-requirements.in, with warm and cold caches. Those benchmarks ran on macOS, and the page itself warns that results can vary dramatically with the operating system, filesystem and set of packages. It also says uv uses reflinking on macOS and hardlinking on Linux when installing, and the documentation describes a global cache that deduplicates dependencies between projects. Treat the headline number as a best case, and measure your own project if speed is the reason you are switching.

uv vs the alternatives

• pip: uv does the same install job and adds the project workflow, but it is not an exact clone. See uv vs pip.
• Poetry and Hatch: uv covers a similar project workflow with Python management included. See Poetry vs uv vs Hatch and Hatch vs uv.
• pyenv: see pyenv vs uv.
• conda: see uv vs venv vs conda.

In Docker and CI

The uv documentation uses uv sync --locked in its GitHub Actions and Docker examples. It makes the install fail if uv.lock is out of date with pyproject.toml, instead of quietly updating it. See Docker for Python with uv. The tool’s resource page is uv, and the whole landscape is covered in Python package managers compared.