ruff Formatting

Expert knowledge for using ruff format as an extremely fast Python code formatter with Black compatibility.

When to Use This Skill

Use this skill when... Use another tool instead when...

Formatting Python files Linting for code issues (use ruff check)

Checking format compliance in CI Type checking (use basedpyright)

Migrating from Black Detecting dead code (use vulture/deadcode)

Setting up format-on-save Running tests (use pytest)

Core Expertise

ruff format Advantages

• 10-30x faster than Black

• Drop-in Black replacement (99.9% compatible)

• Written in Rust for performance

• Supports Black's configuration options

• Format checking and diff preview

• Respects .gitignore automatically

Basic Usage

Simple Formatting

Format current directory

ruff format

Format specific files or directories

ruff format path/to/file.py ruff format src/ tests/

IMPORTANT: Pass directory as parameter to stay in repo root

ruff format services/orchestrator

Format Checking

Check if files are formatted (exit code 1 if not)

ruff format --check

Show diff without modifying files

ruff format --diff

Check specific files

ruff format --check src/ tests/

Preview changes before applying

ruff format --diff services/orchestrator ruff format services/orchestrator # Apply after review

Selective Formatting

Format only Python files

ruff format src/**/*.py

Format excluding tests

ruff format --exclude tests/

Format only changed files (git)

git diff --name-only --diff-filter=d | grep '.py$' | xargs ruff format

Format files in specific directory

ruff format src/core/ src/utils/

Configuration

pyproject.toml

[tool.ruff] line-length = 88 target-version = "py39"

[tool.ruff.format] quote-style = "double" indent-style = "space" skip-magic-trailing-comma = false line-ending = "auto" docstring-code-format = true docstring-code-line-length = "dynamic" exclude = [ "*.pyi", "/pycache", "/node_modules", ".venv", ]

ruff.toml (standalone)

line-length = 88

[format] quote-style = "single" indent-style = "space" skip-magic-trailing-comma = false docstring-code-format = true

Black Compatibility

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

[tool.ruff.format] quote-style = "double" indent-style = "space" skip-magic-trailing-comma = false line-ending = "auto"

Format Workflow

• Preview: ruff format --diff (see changes)

• Check: ruff format --check (CI validation)

• Apply: ruff format (modify files)

• Verify: ruff format --check (confirm)

Best Practices

• Pass directory parameter directly: ruff format src/

• Preview changes first with --diff

• Use one formatter per project (ruff format replaces Black)

• Exclude generated files in pyproject.toml

• Keep pre-commit config in sync with formatter choice

• Enable docstring-code-format for better docs

Agentic Optimizations

Context Command

Format directory ruff format src/

Check formatting ruff format --check

Show diff ruff format --diff

CI check + diff ruff format --check --diff

Format + lint ruff format && ruff check

Format changed files git diff --name-only --diff-filter=d | grep '.py$' | xargs ruff format

Quick Reference

Essential Commands

ruff format # Format current directory ruff format path/to/dir # Format specific directory ruff format --check # Check if formatted ruff format --diff # Show formatting changes ruff format file1.py file2.py # Format specific files ruff format --exclude tests/ # Exclude directory ruff format --line-length 100 # Override line length

Format vs Check

Command Purpose Exit Code Modifies Files

ruff format

Format files 0 Yes

ruff format --check

Validate formatting 1 if unformatted No

ruff format --diff

Show changes 0 No

ruff format --check --diff

Validate + show 1 if unformatted No

Configuration Quick Start

Minimal (Black-compatible)

[tool.ruff] line-length = 88

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

Recommended

[tool.ruff] line-length = 88 target-version = "py311"

[tool.ruff.format] quote-style = "double" indent-style = "space" skip-magic-trailing-comma = false docstring-code-format = true line-ending = "auto" exclude = [ ".pyi", "migrations/**/.py", ]

For detailed examples, advanced patterns, integration guides, and migration checklists, see REFERENCE.md.