uv — User Guide

1. Quick Start

uv is an extremely fast Python package and project manager, written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more — in a single, self-contained binary that installs in seconds.

Key features:

• 10–100x faster than pip for installs and resolution
• Manages Python versions, virtual environments, projects, tools, and scripts
• Provides both a pip-compatible CLI and a first-class project interface with lockfiles
• Supports workspaces, dependency groups, and inline script metadata
• Publishes packages to PyPI with trusted publishing support
• Audits dependencies for known vulnerabilities
• Works on Linux, macOS, and Windows (x86_64, aarch64, arm, and more)
• Ships as a single static binary with no Python dependency

Prerequisites: A terminal. uv can install Python for you — no prior Python installation required.

Install and run in 30 seconds:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip

pip install uv

uv init my-project && cd my-project
uv add requests
uv run python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"

Resolved 5 packages in 120ms
Installed 5 packages in 45ms
 + certifi==2024.8.30
 + charset-normalizer==3.3.2
 + idna==3.10
 + requests==2.32.3
 + urllib3==2.2.3
{'origin': '203.0.113.42'}

Tip

Use uvx (alias for uv tool run) to run CLI tools without installing them: uvx ruff check .

What to try next:

• Install Python: uv python install 3.12
• Run a script: uv run script.py
• Add dev dependencies: uv add --group dev pytest
• See the Configuration section for pyproject.toml and uv.toml settings

2. Installation

System Requirements

Installation Methods

Standalone Installer (Recommended)

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew

brew install uv

pip / pipx

pip install uv
# or
pipx install uv

Cargo

cargo install --git https://github.com/astral-sh/uv uv

Docker

FROM ghcr.io/astral-sh/uv:latest AS uv
COPY --from=uv /uv /usr/local/bin/uv

Conda

conda install -c conda-forge uv

Important

The standalone installer places uv in ~/.local/bin (Unix) or %USERPROFILE%\.local\bin (Windows). Ensure this directory is on your PATH.

Post-Install Verification

uv --version

uv 0.11.7

uv python list

cpython-3.13.3-linux-x86_64-gnu    <download available>
cpython-3.12.10-linux-x86_64-gnu   <download available>
cpython-3.11.12-linux-x86_64-gnu   /usr/bin/python3.11
...

Self-Update

uv self update

Tip

Pin a specific version: uv self update 0.11.7

Shell Completion

# Bash
uv generate-shell-completion bash > ~/.local/share/bash-completion/completions/uv

# Zsh
uv generate-shell-completion zsh > ~/.zfunc/_uv

# Fish
uv generate-shell-completion fish > ~/.config/fish/completions/uv.fish

# PowerShell
uv generate-shell-completion powershell > _uv.ps1

Install Troubleshooting

Error: command not found: uv

Cause: The install directory is not on your PATH.

Solution:

1. Add ~/.local/bin to your shell profile:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

2. On Windows, add %USERPROFILE%\.local\bin to your system PATH.

Prevention: The standalone installer prints the required PATH entry — follow its instructions.

Error: TLS/SSL certificate errors

Cause: Corporate proxy or custom CA certificates.

Solution:

uv --system-certs pip install requests

Or set permanently:

export UV_SYSTEM_CERTS=true

Prevention: Set system-certs = true in your uv.toml.

Error: uv self update fails on managed installs

Cause: uv was installed via a package manager (Homebrew, pip, etc.).

Solution: Update via the same package manager that installed it:

brew upgrade uv    # Homebrew
pip install -U uv  # pip

Prevention: Use the standalone installer for self-update support.

3. Configuration

uv reads settings from multiple sources, in order of precedence:

1. CLI flags (highest priority)
2. Environment variables (UV_*)
3. Project config — [tool.uv] in pyproject.toml or uv.toml in the project root
4. User config — ~/.config/uv/uv.toml (Linux/macOS) or %APPDATA%\uv\uv.toml (Windows)
5. System config — /etc/xdg/uv/uv.toml or /etc/uv/uv.toml (Linux), %SYSTEMDRIVE%\ProgramData\uv\uv.toml (Windows)

Minimal uv.toml Example

# ~/.config/uv/uv.toml — user-level defaults
python-preference = "managed-only"
compile-bytecode = true
concurrent-downloads = 16

[pip]
index-url = "https://pypi.org/simple"

Common Settings

Common Environment Variables

Note

See the Admin Guide for the full configuration reference, including all [tool.uv] settings, index configuration, and resolver options.

4. Core Usage

4.1 Project Management

Initialize a Project

uv init my-project
cd my-project

Initialized project `my-project` at `./my-project`

This creates a pyproject.toml, .python-version, README.md, and a src/my_project/__init__.py starter.

# Initialize as a library (with src layout)
uv init --lib my-lib

# Initialize as an application (flat layout)
uv init --app my-app

# Initialize in the current directory
uv init

Add Dependencies

uv add requests
uv add "flask>=3.0"
uv add --group dev pytest ruff mypy
uv add --optional plotting matplotlib

Tip

Use uv add --frozen to add a dependency without resolving — useful for quickly editing pyproject.toml when you plan to lock later.

Remove Dependencies

uv remove requests
uv remove --group dev mypy

Lock Dependencies

uv lock

Resolved 42 packages in 1.2s

This produces a uv.lock file — a cross-platform lockfile that pins every transitive dependency.

# Check if lockfile is current without updating
uv lock --check

# Upgrade all packages
uv lock --upgrade

# Upgrade a specific package
uv lock --upgrade-package requests

Sync Environment

uv sync

Resolved 42 packages in 5ms
Installed 42 packages in 230ms

Syncs the virtual environment to match the lockfile. Creates the venv if it doesn't exist.

# Sync without dev dependencies
uv sync --no-dev

# Sync with specific extras
uv sync --extra plotting

# Sync with specific groups
uv sync --group dev --group docs

Warning

uv sync removes packages not in the lockfile. If you installed packages manually with uv pip install, they will be removed.

Run Commands

uv run python app.py
uv run pytest
uv run -- python -m my_module --arg value

uv run automatically syncs the environment before running. Use --no-sync or set UV_NO_SYNC=1 to skip.

# Run with extra dependencies (not added to project)
uv run --with httpx python -c "import httpx; print(httpx.get('https://httpbin.org/ip').text)"

# Run a specific script
uv run script.py

Show Dependency Tree

uv tree

my-project v0.1.0
├── requests v2.32.3
│   ├── certifi v2024.8.30
│   ├── charset-normalizer v3.3.2
│   ├── idna v3.10
│   └── urllib3 v2.2.3
└── flask v3.0.3
    ├── blinker v1.8.2
    ├── click v8.1.7
    ├── itsdangerous v2.2.0
    ├── jinja2 v3.1.4
    │   └── markupsafe v2.1.5
    └── werkzeug v3.0.4
        └── markupsafe v2.1.5

View / Set Version

# Display current version
uv version

# Set a specific version
uv version 1.2.3

# Bump version
uv version --bump minor

Export Lockfile

# Export to requirements.txt
uv export --format requirements-txt > requirements.txt

# Export without hashes
uv export --format requirements-txt --no-hashes > requirements.txt

4.2 Running Scripts

uv can run standalone Python scripts, including scripts with inline dependency metadata (PEP 723):

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

import requests
print(requests.get("https://httpbin.org/ip").json())

uv run script.py

uv automatically creates a temporary environment with the declared dependencies.

4.3 Python Version Management

# Install a specific Python version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

# List available and installed versions
uv python list

# Find a specific version
uv python find 3.12

# Pin project Python version
uv python pin 3.12

# Uninstall a managed Python
uv python uninstall 3.11

Note

uv downloads Python from the python-build-standalone project by Astral. Set UV_PYTHON_INSTALL_MIRROR to use a custom mirror.

4.4 Tool Management

Tools are Python CLI applications installed in isolated environments. uvx is a shorthand for uv tool run.

# Run a tool without installing it
uvx ruff check .
uvx black --check .

# Install a tool globally
uv tool install ruff
uv tool install 'httpie>=3.0'

# List installed tools
uv tool list

# Upgrade tools
uv tool upgrade ruff
uv tool upgrade --all

# Uninstall
uv tool uninstall ruff

Tip

Each tool gets its own isolated virtual environment under ~/.local/share/uv/tools/ (or UV_TOOL_DIR). Tools never conflict with each other or your projects.

4.5 Virtual Environments

# Create a venv (default: .venv)
uv venv

# Create with a specific Python version
uv venv --python 3.12

# Create at a custom path
uv venv /path/to/env

# Seed with pip and setuptools
uv venv --seed

4.6 pip-Compatible Interface

uv provides a uv pip subcommand that mirrors pip's interface:

# Install packages
uv pip install requests flask

# Install from requirements file
uv pip install -r requirements.txt

# Compile requirements (like pip-tools)
uv pip compile requirements.in -o requirements.txt

# Sync environment to requirements
uv pip sync requirements.txt

# Freeze installed packages
uv pip freeze

# List installed packages
uv pip list

# Show package details
uv pip show requests

# Check for broken dependencies
uv pip check

# Show dependency tree
uv pip tree

# Uninstall
uv pip uninstall requests

Warning

uv pip operates on the active virtual environment or system Python. It does not use project lockfiles — use uv sync for project-based workflows.

4.7 Building and Publishing

# Build sdist and wheel
uv build

# Build only a wheel
uv build --wheel

# Build a specific package in a workspace
uv build --package my-lib

# Publish to PyPI
uv publish

# Publish to a custom registry
uv publish --publish-url https://upload.pypi.org/legacy/ --token pypi-xxx

Important

uv supports trusted publishing on GitHub Actions and GitLab CI/CD. When running in those environments, set --trusted-publishing always to use OIDC tokens instead of API keys.

4.8 Security Auditing

# Audit project dependencies
uv audit

# Audit with a specific vulnerability database token
uv audit --github-token ghp_xxx

# Output in JSON format
uv audit --format json

4.9 Cache Management

# Show cache directory
uv cache dir

# Show cache size
uv cache size

# Clean entire cache
uv cache clean

# Clean cache for a specific package
uv cache clean requests

# Prune unreferenced cache entries
uv cache prune

4.10 Workspaces

Workspaces let you manage multiple related packages in a monorepo:

# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# List workspace members
uv workspace list

# Show workspace metadata
uv workspace metadata

# Run command in workspace context
uv run --package my-lib pytest

# Build a specific member
uv build --package my-lib

5. Common Tasks

Create a FastAPI Application

Goal: Set up a new FastAPI project with development tooling.

Steps:

1. Initialize the project:

   uv init --app my-api
   cd my-api
   

2. Add dependencies:

   uv add fastapi uvicorn[standard]
   uv add --group dev pytest httpx
   

3. Run the development server:

   uv run uvicorn my_api:app --reload
   

Verify: Open http://localhost:8000/docs in a browser.

Migrate from pip/requirements.txt to a uv Project

Goal: Convert an existing pip-based project to use uv's project management.

Steps:

1. Initialize in existing directory:

   uv init
   

2. Import existing dependencies:

   uv add $(cat requirements.txt | grep -v '^#' | tr '\n' ' ')
   

3. Lock and sync:

   uv lock
   uv sync
   

4. Remove old files:

   rm requirements.txt
   

Verify: uv run python -c "import your_package" succeeds.

Use uv in Docker

Goal: Build a minimal Docker image with uv.

FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Copy project files
WORKDIR /app
COPY pyproject.toml uv.lock ./

# Install dependencies (production only)
RUN uv sync --frozen --no-dev --no-editable

# Copy application code
COPY . .

CMD ["uv", "run", "python", "-m", "my_app"]

Tip

Use --frozen in Docker to avoid lockfile updates. Use --compile-bytecode for faster cold starts in containers.

Pin Dependencies for Reproducible Builds

Goal: Lock all transitive dependencies for CI/CD.

Steps:

1. Lock in development:

   uv lock
   

2. Commit uv.lock to version control.
3. In CI, install with --locked:

   uv sync --locked
   

If it fails: The lockfile is out of sync. Run uv lock locally and push the updated uv.lock.

Use a Private Package Index

Goal: Install packages from a private PyPI-compatible registry.

# pyproject.toml
[[tool.uv.index]]
name = "private"
url = "https://private.pypi.example.com/simple"

Authentication options:

# Environment variable
export UV_INDEX_PRIVATE_USERNAME=user
export UV_INDEX_PRIVATE_PASSWORD=token

# Keyring
uv --keyring-provider subprocess pip install my-private-pkg

# URL credentials
uv pip install --index-url https://user:[email removed]/simple my-private-pkg

Run a One-Off Script with Dependencies

Goal: Execute a Python script that declares its own dependencies inline.

# fetch_data.py
# /// script
# requires-python = ">=3.11"
# dependencies = ["httpx", "rich"]
# ///

import httpx
from rich import print
data = httpx.get("https://httpbin.org/json").json()
print(data)

uv run fetch_data.py

uv creates an ephemeral environment, installs httpx and rich, and runs the script.

Use PyTorch with the Correct CUDA Version

Goal: Install PyTorch with automatic CUDA detection.

# pyproject.toml
[tool.uv]
torch-backend = "auto"

uv add torch torchvision

Note

The torch-backend setting is a preview feature. Enable preview mode with uv --preview or UV_PREVIEW=1.

Set Up a Workspace with Multiple Packages

Goal: Manage a monorepo with shared dependencies.

my-workspace/
├── pyproject.toml          # Root workspace
├── packages/
│   ├── core/
│   │   └── pyproject.toml
│   └── cli/
│       └── pyproject.toml

Root pyproject.toml:

[project]
name = "my-workspace"
version = "0.0.0"
requires-python = ">=3.11"

[tool.uv.workspace]
members = ["packages/*"]

Package packages/cli/pyproject.toml:

[project]
name = "my-cli"
version = "0.1.0"
dependencies = ["my-core"]

[tool.uv.sources]
my-core = { workspace = true }

uv lock    # Locks the entire workspace
uv sync    # Syncs all members

Export for Non-uv Environments

Goal: Generate a requirements.txt for environments where uv isn't available.

# With hashes for security
uv export --format requirements-txt > requirements.txt

# Without hashes
uv export --format requirements-txt --no-hashes > requirements.txt

# For production only
uv export --format requirements-txt --no-dev > requirements-prod.txt

Audit for Vulnerabilities

Goal: Check project dependencies for known CVEs.

uv audit

Found 2 vulnerabilities in 1 package

  certifi (2024.2.2)
  ├── GHSA-xqr8-7jwr-rhp7 — certifi: removal of e-Tugra root certificate
  └── PYSEC-2024-91 — certifi uses vulnerable root certificates

  2 vulnerabilities found (fix available: update certifi to >=2024.7.4)

# Ignore a known vulnerability
uv audit --ignore GHSA-xqr8-7jwr-rhp7

Format pyproject.toml

uv format

Normalizes the pyproject.toml — sorts dependencies, normalizes package names, and applies consistent formatting.

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├─ Installation issue → Check PATH, verify with `uv --version`
├─ Resolution failure → Check `uv lock -v` output, try `--exclude-newer`
├─ Build failure → Check build deps, try `uv pip install --no-build-isolation`
├─ Import error after sync → Check `uv sync` output, ensure correct venv
├─ Network/proxy issue → Try `--offline`, `--system-certs`, or proxy env vars
└─ Cache corruption → Run `uv cache clean` and retry

Error: No solution found when resolving dependencies

Cause: Conflicting version requirements between packages.

Solution:

1. Run with verbose output to see the conflict:

   uv lock -v
   

2. Use constraints to narrow the resolution:

   uv add "package>=2.0,<3.0"
   

3. If a pre-release is needed:

   uv lock --prerelease allow
   

Prevention: Use uv tree regularly to understand your dependency graph.

Error: Failed to build <package>

Cause: Missing system libraries or build tools required to compile a source distribution.

Solution:

1. Install system build tools:

   # Debian/Ubuntu
   sudo apt install build-essential python3-dev
   # macOS
   xcode-select --install
   

2. If the package has a wheel available, force it:

   uv add package --no-build
   

Prevention: Set no-build-package = ["problematic-pkg"] in uv.toml if wheels are available.

Error: error: externally-managed-environment

Cause: Attempting to install into a system Python protected by PEP 668.

Solution:

# Use a virtual environment (preferred)
uv venv
uv pip install requests

# Or use uv's project management
uv init && uv add requests

Prevention: Always work within virtual environments or uv projects.

Error: No interpreter found for Python >=3.x

Cause: The required Python version is not installed.

Solution:

uv python install 3.12

Prevention: Set python-downloads = "automatic" to let uv install Python as needed.

Warning

If python-preference = "system-only", uv will not use managed Python installations. Change to "managed" or "managed-only" if you want uv to manage Python for you.

Error: Locked requirements are not up to date

Cause: pyproject.toml was edited but uv.lock was not regenerated.

Solution:

uv lock

Prevention: Run uv lock --check in CI to catch lockfile drift.

Error: SSL/TLS certificate verification failed

Cause: Corporate proxy intercepting HTTPS, or custom CA certificates.

Solution:

# Use system certificate store
export UV_SYSTEM_CERTS=true

# Or allow a specific insecure host
uv --allow-insecure-host private.pypi.example.com pip install package

Prevention: Configure system-certs = true and allow-insecure-host in uv.toml.

Error: Conflicting URLs for package

Cause: Multiple sources resolve the same package to different URLs.

Solution:

1. Check your index configuration in pyproject.toml
2. Use index-strategy = "first-index" (default) to prevent dependency confusion
3. Pin specific sources:

   [tool.uv.sources]
   my-package = { index = "private" }
   

Prevention: Use explicit index assignments for private packages.

Slow resolution or downloads

Cause: Network latency, too many indexes, or cold cache.

Solution:

1. Increase concurrency:

   concurrent-downloads = 32
   

2. Use --offline when the cache is warm
3. Set index-strategy = "first-index" to avoid querying all indexes

Prevention: Keep cache warm; use uv cache prune instead of uv cache clean.

Tip

Run uv lock -v to see timing information for each resolution step. The first run populates the cache; subsequent runs are significantly faster.

7. FAQ

Q: Does uv replace pip?

Yes, for most workflows. uv pip install, uv pip compile, and uv pip sync provide a drop-in pip-compatible interface. The project-based workflow (uv add, uv sync, uv run) is recommended for new projects.

Q: Does uv work with existing requirements.txt files?

Yes. Use uv pip install -r requirements.txt or uv pip sync requirements.txt. To migrate to a uv project, run uv init and uv add your dependencies.

Q: How do I use uv in CI/CD?

Install uv, then use uv sync --locked to install from the lockfile:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --locked
uv run pytest

Q: Can I use uv with Poetry or PDM projects?

uv reads pyproject.toml but uses its own lockfile format (uv.lock). You can migrate by running uv init in an existing project and re-adding dependencies. Use uv export to generate requirements.txt for backward compatibility.

Q: How does uv manage Python versions?

uv downloads pre-built Python interpreters from python-build-standalone (maintained by Astral). They're stored in ~/.local/share/uv/python/. Use uv python install, uv python list, and uv python pin to manage them.

Q: Where does uv store data?

Q: What is uvx?

uvx is an alias for uv tool run. It runs a Python CLI tool in an ephemeral environment without permanently installing it — similar to npx for Node.js.

Q: Can I use uv with Jupyter notebooks?

Yes. Install Jupyter as a tool: uv tool install jupyter. Or within a project: uv add jupyter then uv run jupyter lab.

Q: How do I configure authentication for private indexes?

Options include:

• URL credentials: https://user:token@host/simple
• Environment variables: UV_INDEX_<NAME>_USERNAME / UV_INDEX_<NAME>_PASSWORD
• Keyring: --keyring-provider subprocess
• .netrc file
• uv auth login (preview feature)

Q: What is the difference between uv lock and uv pip compile?

uv lock creates a cross-platform lockfile (uv.lock) from your pyproject.toml project. uv pip compile creates a requirements.txt from input .in files — it's the pip-tools replacement. Use uv lock for projects; use uv pip compile for legacy workflows.

Q: Does uv support editable installs?

Yes. Project packages are installed in editable mode by default during uv sync. For uv pip, use uv pip install -e ..

Q: How do dependency groups work?

Dependency groups (PEP 735) let you organize development dependencies:

[dependency-groups]
dev = ["pytest", "ruff"]
docs = ["sphinx", "furo"]

Install specific groups with uv sync --group dev or uv sync --group docs.

Q: What is --frozen vs --locked?

• --locked: Asserts that uv.lock is up-to-date with pyproject.toml. Fails if not.
• --frozen: Skips lockfile validation entirely. Uses whatever is in uv.lock without checking.

Both skip re-resolving. Use --locked in CI; use --frozen for speed when you know the lock is fine.