# uv — Fast Python Package Manager

LLMS index: [llms.txt](/en/llms.txt)

---

## What is uv

`uv` is a Python package manager written in Rust. It solves one problem: the standard `pip` is slow at resolving dependencies, and `poetry` adds its own project model on top of PEP 621. `uv` works with `pyproject.toml`, is compatible with PEP 621 and PEP 508, and does it significantly faster.

Under the hood is a caching resolver written in Rust that reuses data from pip-compatible indexes (PyPI by default). `uv` can replace `pip`, `pip-tools`, `virtualenv`, and `poetry` in a single tool.

> [!NOTE]
> `uv` does not require an installed Python to install itself, but to work with Python projects you need an interpreter. `uv` can find and manage CPython via `uv python`.

## Installation

The fastest path is the curl script:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

This places the binary in `~/.local/bin`. On systems without curl:

```bash
pip install uv
```

Or download the standalone binary from [GitHub releases](https://github.com/astral-sh/uv/releases).

After installation, verify the version:

```bash
uv --version
```

> [!WARNING]
> If `uv` is not found after installation, make sure `~/.local/bin` is in your `$PATH`. On Debian/Ubuntu, the pip-installed package places it in `/usr/local/bin`.

## Key commands

The project workflow:

```bash
uv init myproject          # creates pyproject.toml with PEP 621 metadata
cd myproject
uv add requests            # adds a dependency and updates uv.lock
uv add --group dev pytest  # adds a dependency to a named group
uv sync                    # synchronizes the environment with the lock file
uv run pytest              # runs a command inside the project's .venv
```

Key flags for daily work:

| Flag | What it does |
|---|---|
| `--system` | Installs a package into the system Python, bypassing venv |
| `--no-dev` | Excludes dev dependencies during sync |
| `--group <name>` | Specifies a named dependency group |
| `--python <version>` | Selects a specific interpreter version |
| `--locked` | Uses the lock file without re-resolving |
| `--quiet` | Minimal output |
| `--verbose` | Detailed output for debugging |

Managing interpreters:

```bash
uv python list             # shows discovered CPython installations
uv python install 3.12     # downloads and caches CPython 3.12
uv python find             # shows the path to the active Python
```

For package-level work without creating a project:

```bash
uv pip install requests    # pip equivalent, but faster
uv pip freeze              # lists installed packages
uv pip uninstall requests  # removes a package
```

> [!TIP]
> `uv sync` recreates `.venv` and installs exactly what is in `uv.lock`. This makes it suitable for CI — the result is deterministic.

## Comparison with pip and poetry

| Aspect | pip | poetry | uv |
|---|---|---|---|
| Implementation language | Python | Python + Rust | Rust |
| Project model | setup.py / pyproject.toml | pyproject.toml (custom format) | pyproject.toml (PEP 621) |
| Resolution speed | Slow | Medium | Fast |
| Lock file | No native | poetry.lock | uv.lock |
| Virtual environment | venv / virtualenv | Built-in | Built-in (.venv) |
| pip compatibility | Full | Partial | Full |
| Replaces pip | — | — | Yes |
| Replaces poetry | — | — | Yes (partially) |

`uv` wins on resolution speed — in astral-sh benchmarks it is 10–50x faster than `pip` on large dependency graphs. At the same time, `uv pip` is fully compatible with pip workflows: `requirements.txt`, `--index-url`, `--find-links`.

> [!WARNING]
> `uv` is under active development. The `uv.lock` format may change between major versions. In production CI pipelines, pin the `uv` version via `uv --version` or install a specific binary.

A common mistake is confusing `uv add` with `uv pip install`. The former writes the dependency into `pyproject.toml` and updates `uv.lock`; the latter works like pip directly. For projects with `pyproject.toml`, use `uv add`. For one-off scripts and Dockerfiles, use `uv pip install`.

Another frequent issue: `uv` cannot find the interpreter if Python is installed in a non-standard path. The fix is `uv python install --force` or explicit specification via `--python /path/to/python`.