---
name: astral-uv
description: Guide for using uv, the extremely fast Python package and project manager. Use this when working with Python projects, scripts, packages, or tools to manage dependencies, environments, and project setup with universal lockfiles for reproducible builds.
---

# uv: Python Package and Project Manager

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

## Navigation Rule

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

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

## Exclusion Rule

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

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

## Workflow Selection Rule

Choose the right workflow based on your use case:

### Scripts Workflow

**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
```

See [references/script-execution.md](references/script-execution.md) for script execution examples.

### Projects Workflow

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

**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
```

See [references/project-setup.md](references/project-setup.md) for project setup examples.

### Tools Workflow

**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
```

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

### Pip Interface Workflow

**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
```

**Best Practice Rule:** Don't use the pip interface unless clearly needed. Don't introduce new `requirements.txt` files. Prefer `uv init` for new projects.

## Migration Rules

### 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
```

See [references/migration.md](references/migration.md) for migration examples.

## Common Pattern Rules

### Don't Use pip in uv Projects Rule

```bash
# Bad
pip install requests

# Good
uv add requests
```

### Don't Run python Directly Rule

```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 Rule

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

# Good
uv run <command>
```

## Documentation Reference

For detailed information, see the official documentation at https://docs.astral.sh/uv/llms.txt

## Additional References

- Lockfile management: See [references/lockfiles.md](references/lockfiles.md)
- Python version management: See [references/python-versions.md](references/python-versions.md)
- Common workflows: See [references/workflows.md](references/workflows.md)