Comprehensive guide for using uv, an extremely fast Python package and project manager written in Rust...
uv is an extremely fast Python package and project manager that replaces pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more. It provides comprehensive project management with a universal lockfile, runs scripts with inline dependency metadata, and includes a pip-compatible interface.
macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
pipx install uv or pip install uvbrew install uvwinget install --id=astral-sh.uv -escoop install main/uvghcr.io/astral-sh/uvInstall packages (pip-compatible):
uv pip install requests
uv pip install -r requirements.txt
uv pip install --editable .
List installed packages:
uv pip list
Uninstall packages:
uv pip uninstall package-name
Create a virtual environment:
uv venv
uv venv .venv
uv venv --python 3.12
Activate virtual environment:
source .venv/bin/activate.venv\Scripts\activateRemove virtual environment:
rm -rf .venv # or rmdir /s .venv on Windows
Install Python versions:
uv python install 3.10 3.11 3.12
uv python install pypy@3.8
List installed Python versions:
uv python list
Pin Python version for a project:
uv python pin 3.11
Use specific Python version:
uv run --python 3.12 -- python script.py
uv venv --python 3.12.0
Run Python scripts with automatic dependency resolution:
uv run script.py
uv run --python 3.11 script.py
Run scripts with inline dependencies (in script comments):
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "requests>=2.28.0",
# "click",
# ]
# ///
Initialize a new project:
uv init my-project
cd my-project
Add dependencies to project:
uv add requests
uv add --dev pytest
uv add "django>=4.0,<5.0"
Remove dependencies:
uv remove requests
Sync dependencies (install from lockfile):
uv sync
Update dependencies:
uv lock --upgrade
uv supports Cargo-style workspaces for scalable projects:
uv init --workspace
# Initialize project
uv init my-project
cd my-project
# Add dependencies
uv add requests pandas
# Run a script
uv run main.py
# Clone and setup
git clone <repo>
cd <repo>
# Install dependencies from lockfile
uv sync
# Run project
uv run main.py
# Install multiple Python versions
uv python install 3.10 3.11 3.12
# Create venv with specific version
uv venv --python 3.12
# Pin version for project
uv python pin 3.12
From pip:
pip install with uv pip installpip freeze > requirements.txt with uv pip compile requirements.inFrom poetry:
uv add instead of poetry adduv sync instead of poetry install# Install and run tools
uv tool install black
uv tool run black .
# Or use uvx (if available)
uvx black .
uv.lock to version control for reproducible buildsuv python pin to ensure consistent Python versions across teamUse uv in Docker containers:
FROM ghcr.io/astral-sh/uv:debian
WORKDIR /app
COPY . .
RUN uv sync
CMD ["uv", "run", "main.py"]
Issue: Command not found after installation
~/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows) to PATHIssue: Python version not found
uv python install <version> to install the required versionIssue: Lockfile conflicts
uv lock to regenerate lockfile, or uv lock --upgrade to update dependenciesFor detailed documentation on specific features, see:
