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

Quick Start

Installing UV

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

[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)

[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

# .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)

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:

• uv Documentation
• Ruff Documentation
• Astral (Parent Company)

GitHub Repositories:

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

Community:

• Ruff Discord
• GitHub Discussions

Troubleshooting

UV Issues:

# 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:

# 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