ruff

name	ruff
description	Fix all Python lint violations and enforce consistent formatting in one command.
license	MIT
compatibility	claude cursor opencode
metadata	{"version":"1.0.0","languages":"python","audience":"developers","workflow":"automation","since":"2026-02-25"}

What I do

I run ruff to auto-fix all fixable lint violations and enforce consistent code formatting in one step:

• Auto-fix lint violations — unused imports, line length, style issues, import sorting, and more
• Enforce formatting — consistent code style via ruff's Black-compatible formatter
• Surface unfixable issues — show exactly which violations need manual attention, with rule codes and locations
• Configure ruff — add a minimal [tool.ruff] section to pyproject.toml if ruff isn't yet configured

When to use me

• You want to clean up a Python file or entire project before committing
• CI is failing on lint or format checks and you want to auto-fix everything fixable
• You want to see what violations remain after auto-fix so you know what to fix manually
• You're setting up ruff in a project that doesn't have it configured yet

Example usage

/ruff
/ruff check
/ruff format
/ruff init
"fix linting"
"fix all lint issues"

---

Workflow

Fixing lint violations automatically

Run ruff check --fix to auto-fix all fixable lint violations in the current directory:

ruff check --fix .

ruff fixes violations it can safely transform automatically — including:

• Unused imports (F401)
• Import sorting (I001) — replaces isort
• Unnecessary f-strings, redundant open modes, and other style issues
• pyupgrade-style modernisations (e.g. Union[X, Y] → X | Y for Python 3.10+)

Interpreting output:

• ruff prints each fixed violation: Fixed 1 error. or Found 3 errors (3 fixed, 0 remaining).
• Exit code 0: all violations fixed or none found
• Exit code 1: violations remain that could not be auto-fixed (see Understanding unfixable violations)

Example output:

Found 5 errors (5 fixed, 0 remaining).

---

Enforcing consistent formatting

Run ruff format to apply consistent code style across all Python files:

ruff format .

ruff's formatter is Black-compatible — it produces the same output as Black for the vast majority of code. It handles:

• Line length normalisation (default 88 characters)
• Quote normalisation (double quotes by default)
• Trailing comma handling
• Blank line normalisation

Formatting is separate from linting: ruff check --fix fixes lint rules; ruff format fixes style. Run both for a complete cleanup:

ruff check --fix . && ruff format .

This is the recommended default invocation — lint first, then format. The order matters because formatting after linting ensures the final output is consistently styled even when lint fixes change code structure.

---

Understanding unfixable violations

After running ruff check --fix ., any remaining output represents violations that require manual attention:

ruff check .    # dry run: show all current violations without fixing

Example output:

src/main.py:42:5: E501 Line too long (96 > 88 characters)
src/utils.py:18:1: F841 Local variable `result` is assigned to but never used
tests/test_api.py:7:1: S101 Use of `assert` detected

Reading the output: file:line:col: RULE-CODE message

Common unfixable rules:

Rule	Name	Fix
E501	Line too long	Manually break the line or raise line-length in config
F841	Unused variable	Remove or use the variable
F811	Redefinition of unused name	Remove duplicate definition
S101	Assert detected	Replace with proper exception in production code
B006	Mutable default argument	Use None default + if arg is None: arg = [] pattern
PLR0913	Too many arguments	Refactor to use a dataclass or config object

When unfixable violations are found, the skill shows the count, lists each with its rule code and location, and explains how to resolve the most common ones.

---

Configuring ruff in pyproject.toml

If ruff is not yet configured in the project, add a [tool.ruff] section to pyproject.toml:

[tool.ruff]
line-length = 88
target-version = "py311"    # match your Python version

[tool.ruff.lint]
select = ["E", "F", "I", "B", "S"]   # pycodestyle + pyflakes + isort + bugbear + bandit
ignore = ["S101"]                      # ignore assert in tests

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "PLR2004"]  # allow assert and magic values in tests

Alternatively, use a standalone ruff.toml at the project root (same format, without [tool.ruff] prefix):

line-length = 88
target-version = "py311"

[lint]
select = ["E", "F", "I"]

Rule set guidance:

Code	Ruleset	Replaces
E, W	pycodestyle	flake8 E/W
F	pyflakes	flake8 F
I	isort	isort
B	flake8-bugbear	flake8-bugbear
S	flake8-bandit	bandit
UP	pyupgrade	pyupgrade
RUF	ruff-specific	—

Start with ["E", "F", "I"] as a minimal set and add more as your project adopts stricter standards.

---

Tips for Success

1. Run ruff check --fix . && ruff format . as your standard cleanup — this covers both lint and format in one pass. Alias it or add it to a Makefile target.

2. Dry run before fixing: ruff check . (no --fix) shows all violations without modifying files — useful to understand the scope before applying changes.

3. ruff replaces multiple tools — ruff covers flake8, isort, pyupgrade, and parts of pylint. If you're migrating, you can remove those tools from pyproject.toml dev dependencies once ruff is configured.

4. Add ruff to pre-commit: ruff runs in milliseconds on large codebases, making it ideal for pre-commit hooks. The official hooks are available at github.com/astral-sh/ruff-pre-commit.

5. CI auto-patch: In CI, run ruff check --fix . && ruff format . && git diff --exit-code to fail the build if unfixed violations or unformatted files are committed.

6. Check ruff is installed: ruff --version. Install with pip install ruff, uv add --dev ruff, or brew install ruff.

7. E501 (line too long) is often not worth fixing manually — consider raising line-length in [tool.ruff] to 100 or 120 if your codebase has many long lines and reformatting isn't feasible.