# uv and Ruff: A Practical Python Tooling Cheatsheet

Canonical URL: https://www.harjotrana.com/blog/uvx-and-ruff-cheatsheet
Author: Harjot Singh Rana
Published: 2025-10-08
Reading time: 7 min

> Replacing pip, venv, black, and flake8 with two Rust binaries, and what changes day to day.

Quick reference for common UV and Ruff commands.

## UV Commands

### Environment Management

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Clear cache
uv cache clean

# Show cache directory
uv cache dir
```

## Ruff Commands

### Linting

```bash
# 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

```bash
# 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

```bash
# 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

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

### Daily Development

```bash
# 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

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

### Adding Dependencies

```bash
# 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

```python
# 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

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

### Ruff not formatting in VS Code

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

### Dependencies not syncing

```bash
# 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

More writing: https://www.harjotrana.com/blog

---

Site guide for agents: https://www.harjotrana.com/llms.txt · Full site as Markdown: https://www.harjotrana.com/llms-full.txt · Sitemap: https://www.harjotrana.com/sitemap.xml · Developer resources: https://www.harjotrana.com/developers