# UV: Complete Guide

UV is an extremely fast Python package and project manager, written in Rust. It's 10-100x faster than pip and replaces multiple tools in the Python ecosystem.

## Table of Contents

1. [Installation](#installation)
2. [Project Management](#project-management)
3. [Dependency Management](#dependency-management)
4. [Python Version Management](#python-version-management)
5. [Tool Management](#tool-management)
6. [The pip Interface](#the-pip-interface)
7. [Scripts](#scripts)
8. [Building and Publishing](#building-and-publishing)
9. [Configuration](#configuration)
10. [Caching](#caching)

## Installation

### Standalone Installer (Recommended)

**macOS and Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Alternative Methods

**With Homebrew:**
```bash
brew install uv
```

**With pip:**
```bash
pip install uv
```

**With pipx:**
```bash
pipx install uv
```

**With conda:**
```bash
conda install -c conda-forge uv
```

### Upgrading UV

**If installed with standalone installer:**
```bash
uv self update
```

**If installed with pipx:**
```bash
pipx upgrade uv
```

### Shell Autocompletion

**Bash:**
```bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
```

**Zsh:**
```bash
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
```

**Fish:**
```bash
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish
```

**PowerShell:**
```powershell
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'
```

## Project Management

### Creating a New Project

```bash
# Initialize a new project
uv init my-project
cd my-project

# Project structure created:
# my-project/
# ├── .gitignore
# ├── .python-version
# ├── README.md
# ├── hello.py
# └── pyproject.toml
```

### Project Structure

UV creates a standardized project structure:

**pyproject.toml:**
```toml
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
```

### Running Project Code

```bash
# Run a Python file in the project environment
uv run python hello.py

# Run a specific command
uv run pytest

# Run with specific Python version
uv run --python 3.12 python hello.py
```

### Project Commands

```bash
# Initialize existing directory as project
uv init .

# Sync environment with dependencies
uv sync

# Lock dependencies
uv lock

# Clean up project
uv cache clean
```

## Dependency Management

### Adding Dependencies

```bash
# Add a production dependency
uv add requests

# Add multiple dependencies
uv add requests pandas numpy

# Add with version constraint
uv add "requests>=2.31.0"
uv add "pandas<3.0.0"

# Add from git repository
uv add git+https://github.com/user/repo.git

# Add from local path
uv add ../path/to/package
```

### Development Dependencies

```bash
# Add development dependencies
uv add --dev pytest black ruff

# Add to specific dependency group
uv add --group docs sphinx sphinx-rtd-theme
```

### Optional Dependencies

```bash
# Add pandas with optional dependencies
uv add pandas --optional plot

# Install with optional dependencies
uv sync --extra plot
```

### Removing Dependencies

```bash
# Remove a dependency
uv remove requests

# Remove development dependency
uv remove --dev pytest
```

### Upgrading Dependencies

```bash
# Upgrade all dependencies
uv lock --upgrade

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

# Sync after upgrade
uv sync
```

### Dependency Groups

```toml
# In pyproject.toml
[project.optional-dependencies]
dev = ["pytest>=7.0.0", "ruff>=0.1.0"]
docs = ["sphinx>=5.0.0", "sphinx-rtd-theme"]
test = ["pytest", "pytest-cov", "pytest-mock"]

[tool.uv]
dev-dependencies = [
    "black>=23.0.0",
]
```

```bash
# Install with specific groups
uv sync --group docs
uv sync --group test

# Install only specific group
uv sync --only-group dev

# Exclude a group
uv sync --no-group docs
```

### Lockfile Management

UV creates a `uv.lock` file that ensures reproducible environments:

```bash
# Create/update lockfile
uv lock

# Sync environment to match lockfile
uv sync

# Upgrade dependencies and update lockfile
uv lock --upgrade

# Export to requirements.txt
uv export -o requirements.txt

# Export for specific groups
uv export --group docs -o requirements-docs.txt
```

## Python Version Management

### Installing Python

```bash
# Install specific Python version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

# Install latest patch version
uv python install 3.12
```

### Listing Python Versions

```bash
# List installed Python versions
uv python list

# List only installed versions
uv python list --only-installed

# List all available versions
uv python list --all-versions
```

### Pinning Python Version

```bash
# Pin Python version for project
uv python pin 3.12

# This creates/updates .python-version file
# Pin to specific patch version
uv python pin 3.12.4

# Pin to latest compatible version
uv python pin 3.12
```

### Using Specific Python Version

```bash
# Run with specific Python
uv run --python 3.11 python script.py

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

# Use PyPy
uv run --python [email protected] python script.py
```

### Python Discovery

UV automatically discovers Python installations from:
- System Python
- Homebrew Python
- pyenv Python
- conda Python
- Downloaded UV-managed Python

## Tool Management

UV can run and install command-line tools like `pytest`, `black`, `ruff`, etc.

### Running Tools (uvx)

```bash
# Run tool in ephemeral environment
uvx ruff check .
uvx black .
uvx pytest

# Equivalent to:
uv tool run ruff check .
```

### Installing Tools

```bash
# Install tool globally
uv tool install ruff

# Install specific version
uv tool install "ruff==0.1.0"

# Upgrade installed tool
uv tool upgrade ruff

# List installed tools
uv tool list

# Uninstall tool
uv tool uninstall ruff
```

### Tool Directory

Tools are installed in:
- **macOS/Linux**: `~/.local/share/uv/tools`
- **Windows**: `%APPDATA%\uv\tools`

## The pip Interface

UV provides a drop-in replacement for pip commands:

### Installation Commands

```bash
# Install packages
uv pip install requests

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

# Install in editable mode
uv pip install -e .

# Uninstall package
uv pip uninstall requests
```

### Environment Management

```bash
# Create virtual environment
uv venv

# Create with specific Python
uv venv --python 3.12

# Create with specific name
uv venv .venv-custom

# Activate (same as standard venv)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows
```

### Dependency Resolution

```bash
# Compile requirements
uv pip compile requirements.in -o requirements.txt

# With upgrades
uv pip compile requirements.in --upgrade

# Platform-independent (universal)
uv pip compile requirements.in --universal

# Sync environment
uv pip sync requirements.txt
```

### Listing and Freezing

```bash
# List installed packages
uv pip list

# Freeze dependencies
uv pip freeze

# Freeze to file
uv pip freeze > requirements.txt
```

## Scripts

UV can manage dependencies for single-file scripts:

### Inline Script Dependencies

```python
# script.py
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "pandas",
# ]
# ///

import requests
import pandas as pd

response = requests.get("https://api.example.com/data")
df = pd.DataFrame(response.json())
print(df)
```

```bash
# Add dependencies to script
uv add --script script.py requests pandas

# Run script (UV auto-installs dependencies)
uv run script.py
```

### Script Management

```bash
# Run script with inline dependencies
uv run script.py

# Run with specific Python version
uv run --python 3.12 script.py
```

## Building and Publishing

### Building Packages

```bash
# Build wheel and sdist
uv build

# Build only wheel
uv build --wheel

# Build only sdist
uv build --sdist

# Build to specific directory
uv build --out-dir dist/
```

### Publishing Packages

```bash
# Publish to PyPI
uv publish

# Publish to TestPyPI
uv publish --publish-url https://test.pypi.org/legacy/

# Publish with token
uv publish --token <token>

# Publish with username/password
uv publish --username <user> --password <pass>
```

### Package Configuration

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package"
version = "0.1.0"
description = "My awesome package"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "[email protected]"}
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
]
dependencies = [
    "requests>=2.31.0",
]

[project.urls]
Homepage = "https://github.com/user/repo"
Documentation = "https://docs.example.com"
Repository = "https://github.com/user/repo.git"
```

## Configuration

### pyproject.toml Configuration

```toml
[tool.uv]
# Python version constraints
python = ">=3.11"

# Package indexes
index-url = "https://pypi.org/simple"
extra-index-url = ["https://example.com/simple"]

# Dependency resolution
resolution = "highest"  # or "lowest", "lowest-direct"

# Package sources
[tool.uv.sources]
my-package = { git = "https://github.com/user/repo.git" }
local-package = { path = "../local-package" }

# Dependency groups
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]
```

### Environment Variables

```bash
# Custom Python installation directory
export UV_PYTHON_INSTALL_DIR="$HOME/.python"

# Custom cache directory
export UV_CACHE_DIR="$HOME/.cache/uv"

# Disable cache
export UV_NO_CACHE=1

# Custom index URL
export UV_INDEX_URL="https://pypi.org/simple"

# Offline mode
export UV_OFFLINE=1
```

### UV Settings File

Create `~/.config/uv/uv.toml` (or `%APPDATA%\uv\uv.toml` on Windows):

```toml
# Global UV configuration
native-tls = true
no-cache = false
cache-dir = "~/.cache/uv"

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

## Caching

UV uses aggressive caching for speed:

### Cache Location

- **macOS/Linux**: `~/.cache/uv`
- **Windows**: `%LOCALAPPDATA%\uv\cache`

### Cache Commands

```bash
# View cache directory
uv cache dir

# Clean cache
uv cache clean

# Clean specific package
uv cache clean requests

# Prune old cache entries
uv cache prune
```

### Cache Behavior

UV caches:
- Downloaded packages and wheels
- Built wheels from source distributions
- Package metadata
- Git repositories
- Python installations

## Performance Tips

**Parallel Downloads:**
- UV downloads packages in parallel by default
- Uses global cache to avoid re-downloads

**Universal Resolution:**
- Create platform-independent lockfiles
- Faster CI/CD across different platforms

```bash
uv lock --universal
```

**Offline Mode:**
```bash
# Use only cached packages
uv sync --offline
```

**Pre-warming Cache:**
```bash
# Download all dependencies without installing
uv sync --no-install
```

## Common Issues and Solutions

### Permission Denied

```bash
# Change ownership of UV directory
sudo chown -R $USER ~/.local/share/uv  # macOS/Linux
```

### Python Version Not Found

```bash
# Install the required Python version
uv python install 3.12

# Or point to existing Python
uv venv --python /usr/bin/python3.12
```

### Dependency Conflicts

```bash
# Try different resolution strategy
uv lock --resolution lowest

# Override specific package version
uv add "package==1.0.0"

# Check for conflicts
uv pip tree
```

### Cache Issues

```bash
# Clear cache and reinstall
uv cache clean
uv sync --reinstall
```

## Best Practices

1. **Always use lockfiles** for reproducible environments
2. **Pin Python versions** in projects with `.python-version`
3. **Use dependency groups** to organize dependencies
4. **Leverage the cache** - don't disable it unless necessary
5. **Use `uv run`** instead of activating virtualenvs
6. **Export requirements.txt** for compatibility with other tools
7. **Use `uvx`** for one-off tool executions
8. **Configure in pyproject.toml** for project-specific settings

## Comparison with Other Tools

| Feature | uv | pip | poetry | conda |
|---------|-----|-----|--------|-------|
| Speed | 10-100x | 1x | 2-5x | 0.5x |
| Lockfiles | ✅ | ❌ | ✅ | ✅ |
| Python Management | ✅ | ❌ | ❌ | ✅ |
| Project Init | ✅ | ❌ | ✅ | ❌ |
| Tool Running | ✅ | ❌ | ❌ | ❌ |
| Universal Locks | ✅ | ❌ | ❌ | ✅ |
| Written in | Rust | Python | Python | Python |
| Memory Usage | Low | Medium | Medium | High |

## Resources

- [UV Documentation](https://docs.astral.sh/uv/)
- [UV GitHub](https://github.com/astral-sh/uv)
- [UV Benchmarks](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md)
- [PEP 751 - Lockfile Standard](https://peps.python.org/pep-0751/)