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