Uv

Add to specific dependency group:

uv add --group <group-name> <package-name>

Add optional dependency (extra):

uv add --optional <extra-name> <package-name>

Add from alternative source:

uv add git+https://github.com/user/repo
uv add ./local/path
uv add "package @ git+https://github.com/user/repo@tag"

Add from specific index:

uv add torch --index custom-index=https://example.com/simple

Remove dependencies

Remove package from project:

uv remove <package-name>

Remove from specific group:

uv remove --dev <package-name>
uv remove --group <group-name> <package-name>
uv remove --optional <extra-name> <package-name>

Update dependencies

Update package to latest compatible version:

uv add <package-name> --upgrade-package <package-name>

Python Version Management

Install Python

Install latest Python:

uv python install

Install specific version:

uv python install 3.12
uv python install 3.11 3.12
uv python install [email protected]

List available versions:

uv python list

Upgrade Python version:

uv python upgrade 3.12
uv python upgrade

Request Python version

Request specific Python version for commands:

uv run --python 3.12 python script.py
uvx --python 3.10 ruff
uv tool install --python 3.11 mypy

Running Commands in Projects

Run commands in project environment

Run commands with project dependencies available:

uv run python -c "import mypackage"
uv run pytest
uv run my-script.sh

Run with additional dependencies for that invocation only:

uv run --with httpx==0.26.0 python -c "import httpx"
uv run --with "pytest<8" pytest

Run scripts with inline script metadata:

Scripts with # /// script blocks run in isolated environments:

# /// script
# dependencies = ["httpx"]
# ///
import httpx

Execute with: uv run script.py

Running Tools

Run tools without installing (uvx)

Run a tool in temporary environment:

uvx ruff check .
uvx pycowsay "hello"
uvx mkdocs build

Run specific version:

uvx [email protected] check
uvx ruff@latest check

Run with extras:

uvx --from 'mypy[faster-cache,reports]' mypy

Run with additional dependencies:

uvx --with mkdocs-material mkdocs build

Run from different source:

uvx --from git+https://github.com/user/repo toolname
uvx --from 'package==1.0.0' command

Run with different Python version:

uvx --python 3.10 toolname

Install tools persistently

Install tool to PATH:

uv tool install ruff
uv tool install 'httpie>=1.0.0'
uv tool install git+https://github.com/user/repo

Install with extras:

uv tool install mkdocs --with mkdocs-material

Upgrade tool:

uv tool upgrade ruff
uv tool upgrade --all

Project Management

Initialize project

Create new project:

uv init
uv init my-project

Create virtual environment:

uv venv

Sync dependencies to environment:

uv sync

Key Differences from pip

• Use uv add instead of pip install
• Use uv remove instead of pip uninstall
• Dependencies managed in pyproject.toml, not requirements.txt
• Automatic lockfile generation
• Supports workspace and dependency groups
• Faster than pip by default

When to use which command

Important Notes

• uv automatically downloads Python versions when needed
• Use uv run when tool needs project installed (pytest, mypy)
• Use uvx when tool doesn't need project (ruff, black)
• Tools installed with uv tool install are isolated from project dependencies
• Default Python version is auto-detected; use --python to specify
• uv add creates/updates pyproject.toml automatically
• Lockfile is at uv.lock - commit this to version control