uv-package-manager

uv --version
# uv 0.x.x

# Create new project with virtual environment
uv init my-project
cd my-project
 
# Or create in current directory
uv init .
 
# Initialize creates:
# - .python-version (Python version)
# - pyproject.toml (project config)
# - README.md
# - .gitignore

# Install packages (creates venv if needed)
uv add requests pandas
 
# Install dev dependencies
uv add --dev pytest black ruff
 
# Install from requirements.txt
uv pip install -r requirements.txt
 
# Install from pyproject.toml
uv sync

# Create virtual environment with uv
uv venv
 
# Create with specific Python version
uv venv --python 3.12
 
# Create with custom name
uv venv my-env
 
# Create with system site packages
uv venv --system-site-packages
 
# Specify location
uv venv /path/to/venv

# Linux/macOS
source .venv/bin/activate
 
# Windows (Command Prompt)
.venv\Scripts\activate.bat
 
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
 
# Or use uv run (no activation needed)
uv run python script.py
uv run pytest

# Run Python script (auto-activates venv)
uv run python app.py
 
# Run installed CLI tool
uv run black .
uv run pytest
 
# Run with specific Python version
uv run --python 3.11 python script.py
 
# Pass arguments
uv run python script.py --arg value

# Add package (adds to pyproject.toml)
uv add requests
 
# Add with version constraint
uv add "django>=4.0,<5.0"
 
# Add multiple packages
uv add numpy pandas matplotlib
 
# Add dev dependency
uv add --dev pytest pytest-cov
 
# Add optional dependency group
uv add --optional docs sphinx
 
# Add from git
uv add git+https://github.com/user/repo.git
 
# Add from git with specific ref
uv add git+https://github.com/user/repo.git@v1.0.0
 
# Add from local path
uv add ./local-package
 
# Add editable local package
uv add -e ./local-package

# Remove package
uv remove requests
 
# Remove dev dependency
uv remove --dev pytest
 
# Remove multiple packages
uv remove numpy pandas matplotlib

# Upgrade specific package
uv add --upgrade requests
 
# Upgrade all packages
uv sync --upgrade
 
# Upgrade package to latest
uv add --upgrade requests
 
# Show what would be upgraded
uv tree --outdated

# Generate uv.lock file
uv lock
 
# Update lock file
uv lock --upgrade
 
# Lock without installing
uv lock --no-install
 
# Lock specific package
uv lock --upgrade-package requests

# Install Python version
uv python install 3.12
 
# Install multiple versions
uv python install 3.11 3.12 3.13
 
# Install latest version
uv python install
 
# List installed versions
uv python list
 
# Find available versions
uv python list --all-versions

# Set Python version for project
uv python pin 3.12
 
# This creates/updates .python-version file
 
# Use specific Python version for command
uv --python 3.11 run python script.py
 
# Create venv with specific version
uv venv --python 3.12

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
    "click>=8.1.0",
]
 
[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]
docs = [
    "sphinx>=7.0.0",
    "sphinx-rtd-theme>=1.3.0",
]
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.uv]
dev-dependencies = [
    # Additional dev dependencies managed by uv
]
 
[tool.uv.sources]
# Custom package sources
my-package = { git = "https://github.com/user/repo.git" }

# Migrate from requirements.txt
uv add -r requirements.txt
 
# Migrate from poetry
# Already have pyproject.toml, just use:
uv sync
 
# Export to requirements.txt
uv pip freeze > requirements.txt
 
# Export with hashes
uv pip freeze --require-hashes > requirements.txt