uv

uv Skill

Extremely fast Python package and project manager by Astral (Ruff creators).

Overview

uv is a single tool that replaces:

• pip/pip-tools - Package installation and dependency resolution
• virtualenv/venv - Virtual environment creation
• pyenv - Python version management
• pipx - Tool installation and execution
• poetry/pdm - Project and dependency management
• twine - Package publishing

Key Features:

• 10-100x faster than pip
• Universal lockfile (uv.lock) for reproducible builds
• Automatic Python version management
• Built-in tool execution (uvx)
• PEP 723 inline script dependencies
• Drop-in pip compatibility

Quick Reference

Task	Command
New project	uv init
New library	uv init --lib
Add package	uv add <pkg>
Add dev dependency	uv add --dev <pkg>
Remove package	uv remove <pkg>
Install all deps	uv sync
Install (CI/prod)	uv sync --locked
Run command	uv run <cmd>
Run tool (no install)	uvx <tool>
Install Python	uv python install 3.12
Pin Python version	uv python pin 3.12
Update all deps	uv lock --upgrade
Update one package	uv lock --upgrade-package <pkg>
Show dep tree	uv tree
Build package	uv build
Publish to PyPI	uv publish

Quick Start

Installation

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

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

# Via pip/pipx
pipx install uv
pip install uv

# Homebrew
brew install uv

Shell Completion

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

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish

Essential Commands

1. Starting a Project

# Create new project
uv init my-project          # Application (default)
uv init --lib my-library    # Library (src layout, build backend)
uv init --app my-app        # Explicit application

# Set Python version
uv python pin 3.12          # Creates .python-version

# Install Python if needed
uv python install 3.12

2. Managing Dependencies

# Add packages
uv add requests flask       # Production dependencies
uv add --dev pytest ruff    # Development dependencies
uv add --group test pytest  # Specific dependency group
uv add --optional api flask # Optional extra
uv add "httpx>=0.20"        # With version constraint

# Remove packages
uv remove requests
uv remove --dev pytest

# Update packages
uv lock --upgrade                    # All packages
uv lock --upgrade-package requests   # Single package

# View dependencies
uv tree                     # Full tree
uv tree --depth 2           # Limited depth

3. Syncing Environment

# Install all dependencies
uv sync                     # Default (includes dev)
uv sync --locked            # CI/production (strict)
uv sync --frozen            # Don't update lockfile
uv sync --no-dev            # Exclude dev dependencies
uv sync --all-extras        # Include optional extras

4. Running Code

# Run in project environment
uv run python script.py
uv run pytest
uv run flask run

# Run with temporary dependency
uv run --with pandas script.py

# Run tools without installing (uvx)
uvx ruff check .
uvx black --check .
uvx --from httpie http https://example.com

5. Python Version Management

# Install Python versions
uv python install           # Latest version
uv python install 3.12      # Specific version
uv python install 3.11 3.12 3.13  # Multiple

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

# Pin version
uv python pin 3.12          # Project (.python-version)
uv python pin --global 3.12 # User default

# Find Python
uv python find
uv python find ">=3.11"

6. Virtual Environments

# Create (usually automatic)
uv venv                     # Creates .venv
uv venv my-env              # Custom name
uv venv --python 3.12       # Specific Python

# Activate (optional - uv run auto-detects)
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows

7. Global Tools

# Install tools globally
uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install --python 3.12 mypy

# Manage tools
uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff

# Setup PATH
uv tool update-shell

Scripts with Inline Dependencies (PEP 723)

# Initialize script with metadata
uv init --script example.py --python 3.12

# Add dependencies to script
uv add --script example.py requests rich

# Run script (dependencies auto-installed)
uv run example.py

Script format:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich import print
print(requests.get("https://api.example.com").json())

pip-Compatible Interface

# Install packages (requires virtual environment)
uv pip install flask
uv pip install -r requirements.txt
uv pip install -e .         # Editable install

# Uninstall
uv pip uninstall flask

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

# Sync from requirements
uv pip sync requirements.txt

# Freeze environment
uv pip freeze

Building and Publishing

# Build distributions
uv build                    # Creates dist/ with wheel and sdist

# Publish to PyPI
uv publish                  # Requires authentication setup

# Authenticate
uv auth login pypi          # Interactive login
uv auth login pypi --token  # API token

Project Structure

my-project/
├── pyproject.toml          # Project definition (required)
├── uv.lock                 # Lock file (auto-generated)
├── .venv/                  # Virtual environment (gitignored)
├── .python-version         # Python version pin (optional)
└── src/
    └── my_project/
        └── __init__.py

pyproject.toml Example

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
api = ["fastapi", "uvicorn"]
dev = ["pytest", "ruff"]

[project.scripts]
my-cli = "my_project.cli:main"

[dependency-groups]
dev = ["pytest>=8", "ruff", "mypy"]
test = ["pytest-cov"]
docs = ["sphinx", "myst-parser"]

[tool.uv]
dev-dependencies = ["pytest", "ruff"]  # Alternative to dependency-groups
default-groups = ["dev"]

[tool.uv.sources]
# Git dependency
my-lib = { git = "https://github.com/user/my-lib" }
# Local path
local-pkg = { path = "./packages/local-pkg" }
# Specific index
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

Configuration

Configuration Files

Project-level (highest priority):

• uv.toml - Standalone config (preferred)
• pyproject.toml - Under [tool.uv] section

User-level:

• ~/.config/uv/uv.toml (macOS/Linux)
• %APPDATA%\uv\uv.toml (Windows)

Key Environment Variables

Variable	Purpose
UV_CACHE_DIR	Cache directory location
UV_PYTHON	Default Python version
UV_INDEX_URL	Default package index
UV_NO_CACHE	Disable caching
UV_FROZEN	Use lockfile without updating
UV_LOCKED	Assert lockfile unchanged
UV_COMPILE_BYTECODE	Compile to .pyc files
UV_LINK_MODE	Package linking mode (copy, hardlink, symlink)

Common Workflows

New Project Setup

# Create and enter project
uv init my-project
cd my-project

# Add dependencies
uv add flask sqlalchemy
uv add --dev pytest ruff mypy

# Run application
uv run flask run

# Run tests
uv run pytest

Existing Project (from requirements.txt)

# Initialize uv project
uv init

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

# Or use pip interface
uv venv
uv pip install -r requirements.txt

CI/CD Pipeline

# GitHub Actions
- uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
- run: uv sync --locked
- run: uv run pytest

# GitLab CI
variables:
  UV_CACHE_DIR: .uv-cache
  UV_LINK_MODE: copy
image: ghcr.io/astral-sh/uv:latest
script:
  - uv sync --locked
  - uv run pytest

Docker

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./

# Install dependencies only (for caching)
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-install-project

# Copy source and install project
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "my_app"]

direnv Integration

# .envrc
if has uv; then
  VIRTUAL_ENV="$(pwd)/.venv"
  if [[ ! -d "$VIRTUAL_ENV" ]]; then
    uv venv
  fi
  PATH_add "$VIRTUAL_ENV/bin"
  export VIRTUAL_ENV
fi

Migration Guide

From pip + requirements.txt

# Option 1: Initialize new uv project and import dependencies
uv init
# Extract package names from requirements.txt
cat requirements.txt | grep -v "^#" | grep -v "^-e" | \
  cut -d'=' -f1 | cut -d'>' -f1 | xargs uv add

# Option 2: Keep using requirements.txt with uv's pip interface
uv venv
uv pip install -r requirements.txt

# Option 3: Generate lockfile from requirements.txt
uv pip compile requirements.in -o requirements.txt

Key differences:

• uv.lock replaces requirements.txt for locking
• pyproject.toml replaces requirements.in for declaring dependencies
• Use uv run instead of activating virtualenv

From Poetry

# uv can read Poetry's pyproject.toml format
cd existing-poetry

---

*Content truncated.*