UV & Ruff: Modern Python Development Tools

Supercharge your Python development with Astral's blazing-fast tooling suite - uv for package management and ruff for code quality.

When to Use This Skill

Use this skill when you need to:

•Package Management: Install, update, or manage Python dependencies 10-100x faster than pip
•Project Setup: Initialize new Python projects with modern standards
•Python Versions: Install and manage multiple Python versions
•Code Linting: Check Python code for errors and style issues
•Code Formatting: Auto-format Python code to consistent style
•Virtual Environments: Create and manage isolated Python environments
•Migration: Move from pip, conda, poetry, or pipx to modern tooling

Validation

Ensure the environment is ready for this skill:

bash

python scripts/validate_tools.py

Quick Start

Installing UV

bash

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

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

# With Homebrew
brew install uv

# With pipx
pipx install uv

# Verify installation
uv version

Installing Ruff

bash

# With uv (recommended)
uv tool install ruff

# With pip
pip install ruff

# With Homebrew
brew install ruff

# Verify installation
ruff version

Common Workflows

Project Management with UV

bash

# Create a new project
uv init my-project
cd my-project

# Add dependencies
uv add requests pandas numpy

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

# Install all dependencies
uv sync

# Run a script in the project environment
uv run python main.py

# Run a tool (like pytest)
uv run pytest

# Update dependencies
uv lock --upgrade
uv sync

Code Quality with Ruff

bash

# Check for linting errors
ruff check .

# Auto-fix linting errors
ruff check --fix .

# Format code
ruff format .

# Check formatting without changes
ruff format --check .

# Watch mode (continuous linting)
ruff check --watch

# Lint and format in one command
ruff check --fix . && ruff format .

Python Version Management

bash

# Install Python versions
uv python install 3.11 3.12 3.13

# List installed Python versions
uv python list

# Pin Python version for project
uv python pin 3.12

# Use specific Python version
uv run --python 3.11 python script.py

Key Features

UV Features

🚀 Speed: 10-100x faster than pip for package installation

•Parallel downloads and caching
•Rust-powered dependency resolution
•Global package cache for deduplication

📦 All-in-One Tool: Replaces multiple tools

•pip - Package installation
•pip-tools - Dependency locking
•pipx - Tool installation
•poetry - Project management
•pyenv - Python version management
•virtualenv - Environment creation

🔒 Reproducible Environments:

•Universal lockfiles (uv.lock)
•Platform-independent resolution
•Version pinning

Ruff Features

⚡ Extreme Speed: 10-100x faster than existing linters

•Written in Rust for maximum performance
•Processes entire codebases in milliseconds

🔧 Unified Tool: Replaces multiple tools

•Flake8 - Linting
•Black - Formatting
•isort - Import sorting
•pyupgrade - Modern Python syntax
•autoflake - Unused code removal

📏 800+ Rules: Comprehensive code quality

•Pyflakes error detection
•pycodestyle (PEP 8) compliance
•flake8-bugbear best practices
•Many popular Flake8 plugins built-in

Common Patterns

UV Patterns

bash

# Quick tool execution (like npx or pipx)
uvx ruff check .
uvx black .
uvx pytest

# Build and publish packages
uv build
uv publish

# Pip-compatible interface (drop-in replacement)
uv pip install requests
uv pip freeze > requirements.txt
uv pip compile requirements.in
uv pip sync requirements.txt

# Create virtual environment
uv venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Run scripts with inline dependencies
uv add --script my_script.py requests
uv run my_script.py

Ruff Patterns

bash

# Enable specific rule sets
ruff check --select E,W,F,I .

# Ignore specific rules
ruff check --ignore E501 .

# Show fixes that will be applied
ruff check --diff .

# Format with preview features
ruff format --preview .

# Check specific files
ruff check src/main.py tests/test_main.py

# Output formats
ruff check --output-format json .
ruff check --output-format github .

Configuration

UV Configuration (pyproject.toml)

toml

[project]
name = "my-project"
version = "0.1.0"
description = "My Python project"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

[tool.uv.sources]
# Use specific package sources if needed

Ruff Configuration (pyproject.toml)

toml

[tool.ruff]
# Set line length
line-length = 88
indent-width = 4
target-version = "py311"

# Exclude directories
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# Enable rule sets
select = [
    "E",   # pycodestyle errors
    "W",   # pycodestyle warnings
    "F",   # Pyflakes
    "I",   # isort
    "B",   # flake8-bugbear
    "UP",  # pyupgrade
]

# Ignore specific rules
ignore = [
    "E501",  # line too long (handled by formatter)
]

# Allow auto-fix for all enabled rules
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]  # Allow unused imports
"tests/*" = ["S101"]      # Allow assert statements

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "auto"

Integration with Development Tools

Pre-commit Hooks

yaml

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.8
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

CI/CD (GitHub Actions)

yaml

name: Lint and Test

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install dependencies
        run: uv sync

      - name: Lint with ruff
        run: uv run ruff check .

      - name: Format check with ruff
        run: uv run ruff format --check .

      - name: Run tests
        run: uv run pytest

Detailed Documentation

For comprehensive guides and advanced usage, see the reference files:

•
references/uv-guide.md - Complete uv documentation
- •Project management workflows
- •Python version management
- •Package building and publishing
- •Migration from other tools
•
references/ruff-guide.md - Complete ruff documentation
- •All 800+ linting rules
- •Formatting options
- •Rule configuration
- •Editor integration
•
references/migration.md - Migration guides
- •From pip + virtualenv
- •From conda
- •From poetry
- •From pipx
•
references/workflows.md - Advanced workflows
- •Monorepo management
- •Docker integration
- •Production deployments

Resources

Official Documentation:

GitHub Repositories:

•astral-sh/uv
•astral-sh/ruff

Community:

•Ruff Discord
•GitHub Discussions

Troubleshooting

UV Issues:

bash

# Clear cache
uv cache clean

# Reinstall Python
rm -r "$(uv python dir)"
uv python install 3.12

# Reset lockfile
rm uv.lock
uv lock

Ruff Issues:

bash

# Clear cache
ruff clean

# Show current settings
ruff check --show-settings

# List all available rules
ruff rule --all

# Explain a specific rule
ruff rule E501

Notes

•UV and Ruff are both built by Astral and designed to work together seamlessly
•UV automatically creates and manages virtual environments - no manual activation needed
•Ruff can replace Black, isort, Flake8, and more with a single tool
•Both tools are written in Rust for maximum performance
•UV's lockfile format is becoming a Python standard (PEP 751 proposal)
•Ruff is compatible with Black formatting by default

Examples

See examples/project-setup.md for a complete walkthrough of setting up a new project.