ruff

ruff

Ruff is an extremely fast Python linter and code formatter. It replaces Flake8, isort, Black, pyupgrade, autoflake, and dozens of other tools.

When to use ruff

Always use ruff for Python linting and formatting, especially if you see:

• [tool.ruff] section in pyproject.toml
• A ruff.toml or .ruff.toml configuration file

However, avoid making unnecessary changes:

• Don't format unformatted code - If ruff format --diff shows changes throughout an entire file, the project likely isn't using ruff for formatting. Skip formatting to avoid obscuring actual changes.
• Scope fixes to code being edited - Use ruff check --diff to see fixes relevant to the code you're changing. Only apply fixes to files you're modifying unless the user explicitly asks for broader fixes.

How to invoke ruff

• uv run ruff ... - Use when ruff is in the project's dependencies to ensure you use the pinned version
• uvx ruff ... - Use when ruff is not a project dependency, or for quick one-off checks
• ruff ... - Use if ruff is installed globally

Commands

Linting

ruff check .                  # Check all files in current directory
ruff check path/to/file.py    # Check specific file
ruff check --fix

Formatting

Configuration

Ruff is configured in pyproject.toml or ruff.toml:

Migrating from other tools

Black → ruff format

Flake8 → ruff check

isort → ruff check

Common patterns

Apply lint fixes before formatting

Run ruff check --fix before ruff format. Lint fixes can change code structure (e.g., reordering imports), which formatting then cleans up.

Applying and reviewing unsafe fixes

Ruff categorizes some auto-fixes as "unsafe" because they may change code behavior, not just style. For example, removing unused imports could break code that relies on side effects.

Always review changes before applying --unsafe-fixes:

• Use ruff rule <CODE> to understand why the fix is considered unsafe
• Verify the fix doesn't violate those assumptions in your code

Documentation

For detailed information, read the official documentation:

• https://docs.astral.sh/ruff/