Ruff

raw JSON →
0.15.7 verified Tue May 12 auth: no python install: verified quickstart: stale

Extremely fast Python linter and formatter written in Rust by Astral. Current version is 0.15.7. Two separate subcommands: ruff check (linting, replaces Flake8/isort/pyupgrade) and ruff format (formatting, replaces Black). Not a Python library to import — CLI tool only. The format setting and RUFF_FORMAT env var were repurposed/removed; use output-format and RUFF_OUTPUT_FORMAT instead. 2026 style guide introduced in 0.15.0 changes lambda formatting.

pip install ruff

Common errors

error Unknown configuration option: `format` ↓
cause The `format` configuration option in `ruff.toml` (or `pyproject.toml`) was removed in Ruff 0.0.267 and replaced by `output-format` to avoid confusion with the `ruff format` command.
fix
Replace format = "..." with output-format = "..." in your Ruff configuration file.
error Error: Invalid configuration file pyproject.toml: invalid type: string, expected a sequence for key `select` ↓
cause Configuration options like `select`, `ignore`, or `extend-select` expect a TOML array (list of strings) but received a single string.
fix
Change the string value to a list of strings. For example, select = "E,F" should become select = ["E", "F"].
error ModuleNotFoundError: No module named 'ruff' ↓
cause Ruff is a standalone command-line interface (CLI) tool written in Rust, not a Python library intended for direct `import` within Python scripts.
fix
Do not attempt to import ruff in Python code. To use Ruff, execute it as a command from your terminal (e.g., ruff check . or ruff format .).
error error: Unknown lint code: E9999 ↓
cause The specified lint code (e.g., `E9999`) does not exist or is not recognized by Ruff. This often happens when migrating from other linters or due to typos.
fix
Consult the Ruff documentation for a list of valid lint codes and adjust your configuration (e.g., pyproject.toml, ruff.toml, or command-line arguments) to use correct codes.

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.
gotcha The command 'pip install ruff' was executed as Python code, leading to a SyntaxError. Pip commands should be run directly in the shell or via a subprocess call, not as part of a Python script. ↓
fix Execute `pip install ruff` directly in your shell environment or, if running from a Python script, use `subprocess.run(['pip', 'install', 'ruff'], check=True)`.
gotcha Running shell commands (like `pip install`) directly within a Python script will raise a `SyntaxError: invalid syntax`. Python interprets such lines as invalid Python code rather than shell commands. ↓
fix To execute shell commands like `pip install ruff` from within a Python script, use `import subprocess; subprocess.run(['pip', 'install', 'ruff'])` or `import os; os.system('pip install ruff')`.

Install

uv tool install ruff@latest
uv add --dev ruff
pipx install ruff

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) - - - 17.8M
3.10 slim (glibc) - - - 18M
3.11 alpine (musl) - - - 19.7M
3.11 slim (glibc) - - - 20M
3.12 alpine (musl) - - - 11.6M
3.12 slim (glibc) - - - 12M
3.13 alpine (musl) - - - 11.2M
3.13 slim (glibc) - - - 12M
3.9 alpine (musl) - - - 17.3M
3.9 slim (glibc) - - - 18M

Imports

Quickstart stale last tested: 2026-04-23

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
last verified Tue May 12
next check Sat Jun 27