Ruff

Warnings

• breaking The format setting in [tool.ruff] was repurposed: it no longer controls CLI output format. Use output-format instead. The RUFF_FORMAT env var was removed — use RUFF_OUTPUT_FORMAT. Old configs using format = 'json' to get JSON output are silently broken.
  Fix: Replace [tool.ruff] format = 'json' with [tool.ruff] output-format = 'json'. Replace RUFF_FORMAT=json with RUFF_OUTPUT_FORMAT=json.
• breaking 2026 style guide (introduced in 0.15.0) changes lambda formatting — lambda bodies are now parenthesized instead of breaking parameters across lines. Reformatting existing code will produce diffs.
  Fix: Run ruff format . after upgrading to reformat under the 2026 style guide. Review diffs carefully, especially for lambdas as function arguments.
• breaking build/ directory no longer excluded by default. Previously ruff excluded build/, which caused confusion when projects had a legitimate build/ directory. Now build/ is only excluded if in .gitignore or extend-exclude.
  Fix: If you relied on build/ being excluded, add it explicitly: [tool.ruff] extend-exclude = ['build']
• gotcha ruff check and ruff format are separate subcommands — running ruff check does NOT format code. Need both: ruff check --fix && ruff format. In pre-commit, two separate hooks are needed: ruff-check and ruff-format.
  Fix: Use both subcommands. In pre-commit: - id: ruff-check then - id: ruff-format. ruff-check must come BEFORE ruff-format when using --fix.
• gotcha Ruff only enables F (Pyflakes) and a subset of E (pycodestyle) rules by default. Common rules like isort (I), bugbear (B), pyupgrade (UP) must be explicitly selected. Not specifying select means most linting power is unused.
  Fix: Add to [tool.ruff.lint]: select = ['E', 'F', 'B', 'I', 'UP', 'RUF']. Or use select = ['ALL'] with specific ignores.
• gotcha --format flag on ruff check and ruff linter was renamed to --output-format. Using --format raises an error.
  Fix: Replace ruff check --format json with ruff check --output-format json.

Install

• uv tool install ruff@latest Via uv (recommended — system-wide)
• uv add --dev ruff Add to project as dev dependency
• pip install ruff Via pip
• pipx install ruff Via pipx (isolated)

Imports

• ruff (CLI)

  # ruff is a CLI tool — not a Python library to import
  # Two separate subcommands:
  
  # Linting (replaces flake8, isort, pyupgrade, etc.)
  ruff check .                  # lint all files
  ruff check . --fix            # lint and auto-fix safe issues
  ruff check . --unsafe-fixes   # also apply unsafe fixes
  
  # Formatting (replaces Black)
  ruff format .                 # format all files
  ruff format . --check         # check only, no changes
  
  # Configuration in pyproject.toml:
  # [tool.ruff]
  # line-length = 88
  # [tool.ruff.lint]
  # select = ["E", "F", "B", "I"]
  # [tool.ruff.format]
  # quote-style = "double"

  ruff is a CLI tool only. Configure via pyproject.toml [tool.ruff] or ruff.toml. Two subcommands: ruff check for linting, ruff format for formatting.

Quickstart

ruff check for linting, ruff format for formatting. Configure in pyproject.toml [tool.ruff].

# Install
pip install ruff

# Lint all Python files in current directory
ruff check .

# Lint with auto-fix
ruff check . --fix

# Format all Python files
ruff format .

# Check formatting without modifying (for CI)
ruff format . --check

# Minimal pyproject.toml config
# [tool.ruff]
# line-length = 88
# target-version = "py311"
#
# [tool.ruff.lint]
# select = ["E", "F", "B", "I", "UP"]
# ignore = ["E501"]
#
# [tool.ruff.format]
# quote-style = "double"
# indent-style = "space"

# Pre-commit hook (pin the version!)
# - repo: https://github.com/astral-sh/ruff-pre-commit
#   rev: v0.15.7
#   hooks:
#     - id: ruff-check
#       args: [--fix]
#     - id: ruff-format