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 .