1# macOS/Linux
 2curl -LsSf https://astral.sh/uv/install.sh | sh
 3
 4# Windows (PowerShell)
 5powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 6
 7# Using pip (if you already have Python)
 8pip install uv
 9
10# Using Homebrew (macOS)
11brew install uv
12
13# Using cargo (if you have Rust)
14cargo install --git https://github.com/astral-sh/uv uv

1uv --version
2# uv 0.x.x

 1# Create new project with virtual environment
 2uv init my-project
 3cd my-project
 4
 5# Or create in current directory
 6uv init .
 7
 8# Initialize creates:
 9# - .python-version (Python version)
10# - pyproject.toml (project config)
11# - README.md
12# - .gitignore

 1# Install packages (creates venv if needed)
 2uv add requests pandas
 3
 4# Install dev dependencies
 5uv add --dev pytest black ruff
 6
 7# Install from requirements.txt
 8uv pip install -r requirements.txt
 9
10# Install from pyproject.toml
11uv sync

 1# Create virtual environment with uv
 2uv venv
 3
 4# Create with specific Python version
 5uv venv --python 3.12
 6
 7# Create with custom name
 8uv venv my-env
 9
10# Create with system site packages
11uv venv --system-site-packages
12
13# Specify location
14uv venv /path/to/venv

 1# Linux/macOS
 2source .venv/bin/activate
 3
 4# Windows (Command Prompt)
 5.venv\Scripts\activate.bat
 6
 7# Windows (PowerShell)
 8.venv\Scripts\Activate.ps1
 9
10# Or use uv run (no activation needed)
11uv run python script.py
12uv run pytest

 1# Run Python script (auto-activates venv)
 2uv run python app.py
 3
 4# Run installed CLI tool
 5uv run black .
 6uv run pytest
 7
 8# Run with specific Python version
 9uv run --python 3.11 python script.py
10
11# Pass arguments
12uv run python script.py --arg value

 1# Add package (adds to pyproject.toml)
 2uv add requests
 3
 4# Add with version constraint
 5uv add "django>=4.0,<5.0"
 6
 7# Add multiple packages
 8uv add numpy pandas matplotlib
 9
10# Add dev dependency
11uv add --dev pytest pytest-cov
12
13# Add optional dependency group
14uv add --optional docs sphinx
15
16# Add from git
17uv add git+https://github.com/user/repo.git
18
19# Add from git with specific ref
20uv add git+https://github.com/user/repo.git@v1.0.0
21
22# Add from local path
23uv add ./local-package
24
25# Add editable local package
26uv add -e ./local-package

1# Remove package
2uv remove requests
3
4# Remove dev dependency
5uv remove --dev pytest
6
7# Remove multiple packages
8uv remove numpy pandas matplotlib

 1# Upgrade specific package
 2uv add --upgrade requests
 3
 4# Upgrade all packages
 5uv sync --upgrade
 6
 7# Upgrade package to latest
 8uv add --upgrade requests
 9
10# Show what would be upgraded
11uv tree --outdated

 1# Generate uv.lock file
 2uv lock
 3
 4# Update lock file
 5uv lock --upgrade
 6
 7# Lock without installing
 8uv lock --no-install
 9
10# Lock specific package
11uv lock --upgrade-package requests

 1# Install Python version
 2uv python install 3.12
 3
 4# Install multiple versions
 5uv python install 3.11 3.12 3.13
 6
 7# Install latest version
 8uv python install
 9
10# List installed versions
11uv python list
12
13# Find available versions
14uv python list --all-versions

 1# Set Python version for project
 2uv python pin 3.12
 3
 4# This creates/updates .python-version file
 5
 6# Use specific Python version for command
 7uv --python 3.11 run python script.py
 8
 9# Create venv with specific version
10uv venv --python 3.12

 1[project]
 2name = "my-project"
 3version = "0.1.0"
 4description = "My awesome project"
 5readme = "README.md"
 6requires-python = ">=3.8"
 7dependencies = [
 8    "requests>=2.31.0",
 9    "pydantic>=2.0.0",
10    "click>=8.1.0",
11]
12
13[project.optional-dependencies]
14dev = [
15    "pytest>=7.4.0",
16    "pytest-cov>=4.1.0",
17    "black>=23.0.0",
18    "ruff>=0.1.0",
19    "mypy>=1.5.0",
20]
21docs = [
22    "sphinx>=7.0.0",
23    "sphinx-rtd-theme>=1.3.0",
24]
25
26[build-system]
27requires = ["hatchling"]
28build-backend = "hatchling.build"
29
30[tool.uv]
31dev-dependencies = [
32    # Additional dev dependencies managed by uv
33]
34
35[tool.uv.sources]
36# Custom package sources
37my-package = { git = "https://github.com/user/repo.git" }

 1# Migrate from requirements.txt
 2uv add -r requirements.txt
 3
 4# Migrate from poetry
 5# Already have pyproject.toml, just use:
 6uv sync
 7
 8# Export to requirements.txt
 9uv pip freeze > requirements.txt
10
11# Export with hashes
12uv pip freeze --require-hashes > requirements.txt

 1# Project structure
 2# monorepo/
 3#   packages/
 4#     package-a/
 5#       pyproject.toml
 6#     package-b/
 7#       pyproject.toml
 8#   pyproject.toml (root)
 9
10# Root pyproject.toml
11[tool.uv.workspace]
12members = ["packages/*"]
13
14# Install all workspace packages
15uv sync
16
17# Add workspace dependency
18uv add --path ./packages/package-a

 1# .github/workflows/test.yml
 2name: Tests
 3
 4on: [push, pull_request]
 5
 6jobs:
 7  test:
 8    runs-on: ubuntu-latest
 9
10    steps:
11      - uses: actions/checkout@v4
12
13      - name: Install uv
14        uses: astral-sh/setup-uv@v2
15        with:
16          enable-cache: true
17
18      - name: Set up Python
19        run: uv python install 3.12
20
21      - name: Install dependencies
22        run: uv sync --all-extras --dev
23
24      - name: Run tests
25        run: uv run pytest
26
27      - name: Run linting
28        run: |
29          uv run ruff check .
30          uv run black --check .

 1# Dockerfile
 2FROM python:3.12-slim
 3
 4# Install uv
 5COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 6
 7# Set working directory
 8WORKDIR /app
 9
10# Copy dependency files
11COPY pyproject.toml uv.lock ./
12
13# Install dependencies
14RUN uv sync --frozen --no-dev
15
16# Copy application code
17COPY . .
18
19# Run application
20CMD ["uv", "run", "python", "app.py"]

 1# Multi-stage Dockerfile
 2FROM python:3.12-slim AS builder
 3
 4# Install uv
 5COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 6
 7WORKDIR /app
 8
 9# Install dependencies to venv
10COPY pyproject.toml uv.lock ./
11RUN uv sync --frozen --no-dev --no-editable
12
13# Runtime stage
14FROM python:3.12-slim
15
16WORKDIR /app
17
18# Copy venv from builder
19COPY --from=builder /app/.venv .venv
20COPY . .
21
22# Use venv
23ENV PATH="/app/.venv/bin:$PATH"
24
25CMD ["python", "app.py"]

 1# Create lockfile (uv.lock)
 2uv lock
 3
 4# Install from lockfile (exact versions)
 5uv sync --frozen
 6
 7# Update lockfile without installing
 8uv lock --no-install
 9
10# Upgrade specific package in lock
11uv lock --upgrade-package requests
12
13# Check if lockfile is up to date
14uv lock --check
15
16# Export lockfile to requirements.txt
17uv export --format requirements-txt > requirements.txt
18
19# Export with hashes for security
20uv export --format requirements-txt --hash > requirements.txt

 1# UV automatically uses global cache at:
 2# Linux: ~/.cache/uv
 3# macOS: ~/Library/Caches/uv
 4# Windows: %LOCALAPPDATA%\uv\cache
 5
 6# Clear cache
 7uv cache clean
 8
 9# Check cache size
10uv cache dir

1# UV installs packages in parallel by default
2
3# Control parallelism
4uv pip install --jobs 4 package1 package2
5
6# No parallel (sequential)
7uv pip install --jobs 1 package

1# Install from cache only (no network)
2uv pip install --offline package
3
4# Sync from lockfile offline
5uv sync --frozen --offline

 1# pip
 2python -m venv .venv
 3source .venv/bin/activate
 4pip install requests pandas numpy
 5# ~30 seconds
 6
 7# uv
 8uv venv
 9uv add requests pandas numpy
10# ~2 seconds (10-15x faster)

 1# poetry
 2poetry init
 3poetry add requests pandas
 4poetry install
 5# ~20 seconds
 6
 7# uv
 8uv init
 9uv add requests pandas
10uv sync
11# ~3 seconds (6-7x faster)

1# pip-tools
2pip-compile requirements.in
3pip-sync requirements.txt
4# ~15 seconds
5
6# uv
7uv lock
8uv sync --frozen
9# ~2 seconds (7-8x faster)

 1# Complete workflow
 2uv init my-project
 3cd my-project
 4
 5# Set Python version
 6uv python pin 3.12
 7
 8# Add dependencies
 9uv add fastapi uvicorn pydantic
10
11# Add dev dependencies
12uv add --dev pytest black ruff mypy
13
14# Create structure
15mkdir -p src/my_project tests
16
17# Run tests
18uv run pytest
19
20# Format code
21uv run black .
22uv run ruff check .

 1# Clone repository
 2git clone https://github.com/user/project.git
 3cd project
 4
 5# Install dependencies (creates venv automatically)
 6uv sync
 7
 8# Install with dev dependencies
 9uv sync --all-extras
10
11# Update dependencies
12uv lock --upgrade
13
14# Run application
15uv run python app.py
16
17# Run tests
18uv run pytest
19
20# Add new dependency
21uv add new-package
22
23# Commit updated files
24git add pyproject.toml uv.lock
25git commit -m "Add new-package dependency"

 1# .pre-commit-config.yaml
 2repos:
 3  - repo: local
 4    hooks:
 5      - id: uv-lock
 6        name: uv lock
 7        entry: uv lock
 8        language: system
 9        pass_filenames: false
10
11      - id: ruff
12        name: ruff
13        entry: uv run ruff check --fix
14        language: system
15        types: [python]
16
17      - id: black
18        name: black
19        entry: uv run black
20        language: system
21        types: [python]

 1// .vscode/settings.json
 2{
 3  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
 4  "python.terminal.activateEnvironment": true,
 5  "python.testing.pytestEnabled": true,
 6  "python.testing.pytestArgs": ["-v"],
 7  "python.linting.enabled": true,
 8  "python.formatting.provider": "black",
 9  "[python]": {
10    "editor.defaultFormatter": "ms-python.black-formatter",
11    "editor.formatOnSave": true
12  }
13}

 1# Issue: uv not found
 2# Solution: Add to PATH or reinstall
 3echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
 4
 5# Issue: Wrong Python version
 6# Solution: Pin version explicitly
 7uv python pin 3.12
 8uv venv --python 3.12
 9
10# Issue: Dependency conflict
11# Solution: Check resolution
12uv lock --verbose
13
14# Issue: Cache issues
15# Solution: Clear cache
16uv cache clean
17
18# Issue: Lockfile out of sync
19# Solution: Regenerate
20uv lock --upgrade

 1# Use frozen installs in CI
 2uv sync --frozen
 3
 4# Use offline mode when possible
 5uv sync --offline
 6
 7# Parallel operations (automatic)
 8# uv does this by default
 9
10# Reuse cache across environments
11# uv shares cache globally
12
13# Use lockfiles to skip resolution
14uv sync --frozen  # skips resolution

 1# Before
 2python -m venv .venv
 3source .venv/bin/activate
 4pip install -r requirements.txt
 5
 6# After
 7uv venv
 8uv pip install -r requirements.txt
 9# Or better:
10uv init
11uv add -r requirements.txt

 1# Before
 2poetry install
 3poetry add requests
 4
 5# After
 6uv sync
 7uv add requests
 8
 9# Keep existing pyproject.toml
10# uv reads [project] and [tool.poetry] sections

1# Before
2pip-compile requirements.in
3pip-sync requirements.txt
4
5# After
6uv lock
7uv sync --frozen

 1# Project management
 2uv init [PATH]              # Initialize project
 3uv add PACKAGE              # Add dependency
 4uv remove PACKAGE           # Remove dependency
 5uv sync                     # Install dependencies
 6uv lock                     # Create/update lockfile
 7
 8# Virtual environments
 9uv venv [PATH]              # Create venv
10uv run COMMAND              # Run in venv
11
12# Python management
13uv python install VERSION   # Install Python
14uv python list              # List installed Pythons
15uv python pin VERSION       # Pin Python version
16
17# Package installation (pip-compatible)
18uv pip install PACKAGE      # Install package
19uv pip uninstall PACKAGE    # Uninstall package
20uv pip freeze               # List installed
21uv pip list                 # List packages
22
23# Utility
24uv cache clean              # Clear cache
25uv cache dir                # Show cache location
26uv --version                # Show version