uv and Ruff: A Practical Python Tooling Cheatsheet

Quick reference for common UV and Ruff commands.

UV Commands

Environment Management

# Create virtual environment
uv venv

# Activate environment
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

# Create with specific Python version
uv venv --python 3.11

Package Management

# Install from pyproject.toml
uv pip install -e .
uv pip install -e ".[dev]"  # Include dev dependencies

# Install specific package
uv pip install fastapi
uv pip install "fastapi>=0.109.0"

# Install from requirements.txt
uv pip install -r requirements.txt

# Uninstall package
uv pip uninstall fastapi

# List installed packages
uv pip list

# Show package info
uv pip show fastapi

Running Commands

# Run Python script
uv run python script.py

# Run module
uv run -m pytest

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

Cache Management

# Clear cache
uv cache clean

# Show cache directory
uv cache dir

Ruff Commands

Linting

# Check all files
uv run ruff check .

# Check specific files/directories
uv run ruff check app/ tests/

# Auto-fix issues
uv run ruff check --fix .

# Show all issues (including fixed)
uv run ruff check --show-fixes .

# Watch mode (re-check on file changes)
uv run ruff check --watch .

Formatting

# Format all files
uv run ruff format .

# Format specific files
uv run ruff format app/main.py

# Check formatting without changing files
uv run ruff format --check .

# Show diff of what would change
uv run ruff format --diff .

Configuration

# Show current configuration
uv run ruff config

# Show rule documentation
uv run ruff rule E501

# List all available rules
uv run ruff linter

Common Workflows

Initial Setup

cd auto-mt
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Daily Development

# Format and fix issues before committing
uv run ruff format .
uv run ruff check --fix .

# Run tests
uv run pytest

# Start dev server
uv run uvicorn app.main:app --reload

Pre-Commit Check

# Check everything
uv run ruff check .
uv run ruff format --check .
uv run pytest

Adding Dependencies

# Add to pyproject.toml dependencies list, then:
uv pip install -e ".[dev]"

# Or install directly (but remember to update pyproject.toml!)
uv pip install new-package

VS Code Integration

With the Ruff extension installed and .vscode/settings.json configured:

Auto-format on save: Enabled
Auto-fix on save: Enabled
Import sorting on save: Enabled
Ruler at 100 chars: Visible guide

Keyboard Shortcuts

Cmd/Ctrl + S: Save and auto-format
Cmd/Ctrl + Shift + P -> "Format Document": Manual format
Cmd/Ctrl + Shift + P -> "Organize Imports": Manual import sort

Ruff Rules Reference

Common rule categories enabled in this project:

E: pycodestyle errors (e.g., E501 line too long)
W: pycodestyle warnings
F: pyflakes (e.g., F401 unused import)
I: isort (import sorting)
B: flake8-bugbear (common bugs)
C4: flake8-comprehensions (list/dict comprehensions)
UP: pyupgrade (modern Python syntax)

Example Fixes

# Before
from typing import List
import os
import sys

def foo(x: List[int]) -> List[int]:
    return [i for i in x if i > 0]

# After (Ruff auto-fixes)
import os
import sys

def foo(x: list[int]) -> list[int]:
    return [i for i in x if i > 0]

Performance Comparison

Tool	Time (large codebase)
black + isort + flake8	~10s
ruff check + format	~0.1s

Tool	Installation Time
pip install	~30s
uv pip install	~1s

Troubleshooting

UV not found

# Ensure UV is in PATH
export PATH="$HOME/.cargo/bin:$PATH"
source ~/.bashrc  # or ~/.zshrc

Ruff not formatting in VS Code

Install "Ruff" extension by Astral Software
Check .vscode/settings.json exists
Reload VS Code window
Check output panel: View -> Output -> Ruff

Dependencies not syncing

# Clear cache and reinstall
uv cache clean
rm -rf .venv
uv venv
uv pip install -e ".[dev]"

Resources

UV Docs: https://docs.astral.sh/uv/
Ruff Docs: https://docs.astral.sh/ruff/
Ruff Rules: https://docs.astral.sh/ruff/rules/
VS Code Ruff Extension: https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff