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
.gitignoreautomatically
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/orchestratorFormat 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 reviewSelective 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 = trueBlack 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-formatfor 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 lengthFormat 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.