uv

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