---
name: uv
description:
  Guide for using uv, the Python package and project manager. Use this when
  working with Python projects, scripts, packages, or tools.
---

# uv

uv is an extremely fast Python package and project manager. It replaces pip,
pip-tools, pipx, pyenv, virtualenv, poetry, etc.

## When to use uv

**Always use uv for Python work**, especially if you see:

- The `uv.lock` file
- uv headers in `requirements*` files, e.g., "This file was autogenerated by uv"

Don't use uv in projects managed by other tools:

- Poetry projects (identifiable by `poetry.lock` file)
- PDM projects (identifiable by `pdm.lock` file)

## Choosing the right workflow

### Scripts

**Use when:** Running single Python files and standalone scripts.

**Key commands:**

```bash
uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script
```

### Projects

**Use when:** There is a `pyproject.toml` or `uv.lock`

**Key commands:**

```bash
uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version
```

### Tools

**Use when:** Running command-line tools (e.g., ruff, ty, pytest) without
installation.

**Key commands:**

```bash
uvx <tool> <args>            # Run a tool without installation
uvx <tool>@<version> <args>  # Run a specific version of a tool
```

**Important:**

- `uvx` runs tools from PyPI by package name. This can be unsafe - only run
  well-known tools.
- Only use `uv tool install` only when specifically requested by the user.

### Pip interface

**Use when:** Legacy workflows with `requirements.txt` or manual environment
management, no `uv.lock` present.

**Key commands:**

```bash
uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# Platform independent resolution
uv pip compile --universal requirements.in -o requirements.txt
```

**Important:**

- Don't use the pip interface unless clearly needed.
- Don't introduce new `requirements.txt` files.
- Prefer `uv init` for new projects.

## Migrating from other tools

### pyenv → uv python

```bash
pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default
```

### pipx → uvx

```bash
pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list
```

### pip and pip-tools → uv pip

```bash
pip install package      → uv pip install package
pip install -r req.txt   → uv pip install -r req.txt
pip freeze               → uv pip freeze
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv
```

## Common patterns

### Don't use pip in uv projects

```bash
# Bad
pip install requests

# Good
uv add requests
```

### Don't run python directly

```bash
# Bad
python script.py

# Good
uv run script.py
```

```bash
# Bad
python -c "..."

# Good
uv run python -c "..."
```

```bash
# Bad
python3.12 -c "..."

# Good
uvx python@3.12 -c "..."
```

### Don't manually manage environments in uv projects

```bash
# Bad
python -m venv .venv
source .venv/bin/activate

# Good
uv run <command>
```

## Documentation

For detailed information, read the official documentation:

- https://docs.astral.sh/uv/llms.txt

The documentation links to specific pages for each of these workflows.