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:
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:
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:
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:
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
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
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
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
Bad
pip install requests
Good
uv add requests
Don't run python directly
Bad
python script.py
Good
uv run script.py
Bad
python -c "..."
Good
uv run python -c "..."
Bad
python3.12 -c "..."
Good
uvx python@3.12 -c "..."
Don't manually manage environments in uv projects
Bad
python -m venv .venv source .venv/bin/activate
Good
uv run <command>
Documentation
For detailed information, read the official documentation:
The documentation links to specific pages for each of these workflows.