uv-python

name	uv-python
description	Standardize Python development using UV - a fast, unified package and project manager. Use when creating Python projects, managing dependencies, setting up virtual environments, installing Python versions, or optimizing Python workflows. Replaces pip, virtualenv, pyenv, poetry, and pipx with a single 10-100x faster tool.

uv-python-manager

UV is the modern standard for Python package and project management in 2025, delivering 10-100x speed improvements while unifying pip, virtualenv, pyenv, poetry, and pipx into a single Rust-based tool.

When to Use This Skill

Use this skill when:

• Creating new Python projects
• Managing dependencies and lockfiles
• Setting up virtual environments
• Installing or switching Python versions
• Building or publishing packages
• Optimizing CI/CD pipelines
• Migrating from pip, poetry, or other tools
• Creating portable Python scripts
• Working with Docker containers

Core Principles

1. Project-first workflow: Use uv init and uv add instead of manual configuration
2. Lock file discipline: Always commit uv.lock for reproducibility
3. Universal execution: Use uv run instead of manual environment activation
4. Version pinning: Use .python-version for team consistency
5. Fast by default: Leverage caching and parallel operations (8-100x faster than pip)

Quick Start

Installing UV

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

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

# Update UV
uv self update

Creating a New Project

# Initialize project (creates pyproject.toml, .python-version, .gitignore)
uv init my-project
cd my-project

# Add dependencies
uv add requests fastapi pandas

# Add development dependencies
uv add --dev pytest ruff mypy

# Add to custom groups
uv add --group docs sphinx
uv add --group test pytest-cov

# Run code (auto-syncs environment)
uv run python main.py
uv run pytest

Essential Commands Reference

Project Lifecycle

uv init [name]              # Create new project with structure
uv add <package>            # Add dependency (updates pyproject.toml + uv.lock)
uv add --dev <package>      # Add development dependency
uv add --group <name> <pkg> # Add to custom dependency group
uv remove <package>         # Remove dependency
uv sync                     # Install/sync all dependencies
uv sync --frozen            # Sync without updating lock (CI mode)
uv sync --no-dev            # Production install (exclude dev deps)
uv run <command>            # Run command in project environment
uv build                    # Build distribution packages
uv publish                  # Publish to PyPI

Python Version Management

uv python install 3.12      # Install Python version
uv python install 3.11 3.12 # Install multiple versions
uv python list              # List installed Python versions
uv python pin 3.12          # Pin project to Python version
uv python find              # Show active Python version

Virtual Environments

uv venv                     # Create virtual environment (.venv/)
uv venv --python 3.12       # Create with specific Python version
uv venv my-env              # Create with custom name

Lock File Management

uv lock                     # Update lockfile from pyproject.toml
uv lock --upgrade           # Upgrade all dependencies
uv lock --upgrade-package <pkg>  # Upgrade specific package
uv lock --check             # Verify lock is current (CI check)
uv export --format requirements-txt > requirements.txt  # Export format

Tool Management (replaces pipx)

uvx <tool>                  # Run tool temporarily (no install)
uvx ruff check .            # Example: run ruff once
uv tool install <tool>      # Install tool globally
uv tool list                # List installed tools
uv tool uninstall <tool>    # Remove global tool

Maintenance

uv cache clean              # Clean cache
uv cache dir                # Show cache location
uv self update              # Update UV itself

Project Structure Best Practices

Standard Layout

project/
├── .git/
├── .gitignore          # Auto-generated by uv init
├── .python-version     # Python version pin (COMMIT THIS)
├── README.md           # Setup instructions
├── pyproject.toml      # Project configuration (COMMIT THIS)
├── uv.lock             # Universal lockfile (COMMIT THIS)
├── .venv/              # Virtual environment (DO NOT COMMIT)
├── src/
│   └── package/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

pyproject.toml Structure

[project]
name = "my-app"
version = "0.1.0"
description = "Application description"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0,<3.0.0",      # Range with upper bound
    "pandas>=2.0.0",                 # Minimum version
    "fastapi[standard]>=0.115.0",   # With extras
]

[project.optional-dependencies]
plotting = ["matplotlib>=3.7.0", "seaborn>=0.12.0"]
database = ["sqlalchemy>=2.0.0", "psycopg2-binary>=2.9.0"]

[dependency-groups]
dev = ["pytest>=8.0.0", "ruff>=0.3.0", "mypy>=1.8.0"]
test = ["pytest-cov>=4.1.0", "pytest-asyncio>=0.23.0"]
docs = ["sphinx>=7.0.0", "sphinx-rtd-theme>=2.0.0"]

Key Workflows

Dependency Management

Adding dependencies:

# Single package
uv add requests

# Multiple packages
uv add requests pandas numpy

# With version constraints
uv add "fastapi>=0.115.0,<1.0.0"

# With extras
uv add "fastapi[standard]"

# Development dependencies
uv add --dev pytest ruff mypy

# Optional dependency groups
uv add --optional plotting matplotlib seaborn

Managing versions:

# Upgrade all dependencies
uv lock --upgrade

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

# Pin to latest compatible versions
uv add requests --upgrade

Running Code

Always use uv run instead of activating environments:

# Run Python scripts
uv run python script.py
uv run python -m mymodule

# Run installed tools
uv run pytest
uv run ruff check .
uv run mypy src/

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

# Pass arguments
uv run pytest tests/ -v --cov

Why uv run is better:

• Auto-syncs environment before running
• Works cross-platform without activation scripts
• Ensures reproducibility
• Handles environment discovery automatically

Inline Script Dependencies (PEP 723)

Create portable single-file scripts:

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

Run with: uv run script.py (automatically installs dependencies)

Python Version Management

Project-level pinning:

# Pin Python version for project
uv python pin 3.12

# This creates .python-version file
# Always commit this file to git

# UV will automatically use this version
uv run python --version

Installing Python versions:

# Install specific version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

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

# List installed versions
uv python list

CI/CD Integration

GitHub Actions example:

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up UV
        uses: astral-sh/setup-uv@v6
        with:
          version: "0.9.5"  # Pin UV version
          enable-cache: true
      
      - name: Set up Python
        run: uv python install
      
      - name: Install dependencies
        run: uv sync --frozen  # Use --frozen in CI
      
      - name: Check lock file is current
        run: uv lock --check
      
      - name: Run tests
        run: uv run pytest
      
      - name: Run linting
        run: uv run ruff check .

Docker optimization:

FROM python:3.12-slim

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

# Set working directory
WORKDIR /app

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies with caching
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

# Copy application code
COPY . .

# Compile bytecode for faster startup
ENV UV_COMPILE_BYTECODE=1

# Run application
CMD ["uv", "run", "python", "-m", "myapp"]

Multi-stage Docker build:

# Stage 1: Build
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev --no-editable

# Stage 2: Runtime
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
ENV UV_COMPILE_BYTECODE=1
CMD ["python", "-m", "myapp"]

Migration from Existing Tools

From pip/pip-tools

# Automated migration
uvx migrate-to-uv

# Or manual migration:
# 1. Create UV project
uv init

# 2. Import from requirements.txt
uv add -r requirements.txt
uv add --dev -r requirements-dev.txt

# 3. Commit new files
git add pyproject.toml uv.lock .python-version
git rm requirements.txt requirements-dev.txt

From Poetry

# Automated migration
uvx migrate-to-uv

# UV reads pyproject.toml directly
# Just start using UV commands:
uv sync        # Replaces: poetry install
uv add pkg     # Replaces: poetry add pkg
uv run cmd     # Replaces: poetry run cmd

From virtualenv/venv

# Old workflow:
# python -m venv .venv
# source .venv/bin/activate  # or .venv\Scripts\activate on Windows
# pip install -r requirements.txt

# New workflow:
uv init
uv add -r requirements.txt
uv run python script.py  # No activation needed

Troubleshooting

Common Issues

Lock file out of sync:

# Error: "lock file is out of date"
uv lock  # Regenerate lock file

Python version not found:

# Error: "Python 3.12 not found"
uv python install 3.12

Dependency conflicts:

# Check resolution
uv lock --verbose

# Try upgrading
uv lock --upgrade

# Check specific package
uv lock --upgrade-package problematic-package

Cache issues:

# Clean cache if corrupted
uv cache clean

# Show cache location
uv cache dir

Import resolution issues:

# Ensure environment is synced
uv sync

# Force reinstall
uv sync --reinstall

Best Practices Checklist

• ✅ Always commit uv.lock and .python-version to version control
• ✅ Use uv sync --frozen in CI/CD pipelines
• ✅ Add .venv/ to .gitignore and .dockerignore
• ✅ Pin UV version in CI for consistency
• ✅ Use uv run instead of manual environment activation
• ✅ Specify requires-python range in pyproject.toml
• ✅ Use dependency groups for dev tools, not optional-dependencies
• ✅ Test with --resolution lowest for libraries
• ✅ Enable bytecode compilation in Docker: UV_COMPILE_BYTECODE=1
• ✅ Use cache mounts in Docker for faster builds
• ✅ Run uv lock --check in CI to catch outdated lockfiles
• ✅ Leverage inline script dependencies (PEP 723) for portable tools
• ✅ Document UV setup in README for team onboarding

Performance Impact

UV achieves dramatic speed improvements:

• 8-10x faster than pip without caching
• 80-115x faster with warm cache
• Virtual environment creation: 100ms vs 8 seconds (python -m venv)
• Complex dependency resolution: seconds vs minutes
• CI/CD impact: 30-65% faster builds

This speed enables new workflows like re-syncing environments on every command invocation without performance penalties.

Advanced Topics

For more specialized use cases, see:

• WORKSPACE.md - Monorepo and multi-project setups
• PUBLISHING.md - Building and publishing packages
• SCRIPTS.md - Advanced script management patterns

Key Differences from Other Tools

vs pip

• Speed: 8-100x faster
• Lock files: Built-in universal lockfiles
• Python management: Can install Python versions
• Unified: Replaces pip + pip-tools + virtualenv

vs Poetry

• Speed: Significantly faster resolution and installation
• Lock files: Universal (cross-platform in one file)
• Simpler: Less configuration required
• Compatible: Reads Poetry's pyproject.toml

vs Conda

• Scope: Python-only (doesn't handle system dependencies)
• Speed: Much faster for Python packages
• Compatibility: Standard PyPI ecosystem
• Not a replacement: Use Conda when you need non-Python dependencies

Support and Resources

• Documentation: https://docs.astral.sh/uv/
• GitHub: https://github.com/astral-sh/uv
• Discord: Join Astral's community
• Changelog: https://github.com/astral-sh/uv/releases

Summary

UV standardizes Python development by unifying package management, environment management, Python version management, and script execution into a single fast tool. The key workflow is:

1. uv init to create projects
2. uv add to manage dependencies
3. uv run to execute code
4. uv sync --frozen in CI/CD
5. Commit uv.lock and .python-version

This provides consistent, fast, reproducible Python workflows across all platforms.