Ruff: Python Linter and Formatter

Ruff is a fast Python linter and code formatter from Astral (the makers of uv and ty). It replaces multiple Python code quality tools (like flake8, Black, isort, and pyupgrade) with a single binary.

When to use Ruff

Use Ruff when you want a single, fast tool for linting and formatting Python code instead of maintaining separate configurations for flake8, Black, isort, and other code quality tools. It is a strong default for any Python project, from small scripts to large monorepos, because it handles linting, formatting, and import sorting in one pass with minimal configuration. If you need deeper static analysis beyond what lint rules provide, pair Ruff with a type checker like mypy or pyright; for a comparison with traditional linting, see How do Ruff and Pylint compare?. For a full walkthrough of rule categories, configuration, and migrating an existing project, see Ruff: a complete guide.

Key Features

• Linting: Checks code for errors, style violations, and potential problems using ruff check
• Formatting: Automatically formats code to follow style conventions using ruff format
• Markdown Formatting: Formats Python code blocks embedded in Markdown files and Quarto notebooks using ruff format; recognizes fenced code blocks tagged python, py, pyi, and pycon
• Import Sorting: Orders and groups Python imports systematically via the I rule (see how to sort Python imports with Ruff)
• Code Upgrades: Modernizes Python code syntax automatically (e.g. replacing deprecated patterns with modern equivalents)
• Configuration: Uses standard pyproject.toml for settings

Core Capabilities

Linting Rules

Ruff supports over 950 lint rules drawn from dozens of existing tools, with 413 enabled by default:

• Style checking (PEP 8, via pycodestyle rules)
• Error detection (via pyflakes rules)
• Complexity checking (via mccabe rules)
• Best practice enforcement (e.g. flake8-bugbear, flake8-simplify)
• Type annotation validation (e.g. flake8-annotations)
• Documentation checking (e.g. pydocstyle)
• Code modernization (via pyupgrade rules)

Rules can be individually enabled or disabled, and many include auto-fix support.

Performance

• 10-100x faster than traditional Python tools like flake8 and Black
• Parallel processing for large codebases
• Incremental checking for changed files
• Caching of results

Suppressing Rules

Ruff supports three levels of rule suppression:

Line-level: The # noqa syntax (compatible with flake8) goes at the end of the line:

x = 1  # noqa: F841

The # ruff: ignore syntax can go inline at the end of the line or on the preceding line, covering the full logical line below it:

# ruff: ignore[F841]
x = 1

x = 1  # ruff: ignore[F841]

Block-level: Use # ruff: disable[{code}] and # ruff: enable[{code}] comments to suppress rules for a range of lines:

# ruff: disable[E501]
VALUE_1 = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore"
VALUE_2 = "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo"
# ruff: enable[E501]

File-level: The # ruff: noqa syntax (flake8-compatible) can appear anywhere in the file:

# ruff: noqa: F841

The # ruff: file-ignore syntax must be on its own line at module scope:

# ruff: file-ignore[F841]

Integration

• IDE plugins for real-time feedback
• CI/CD pipeline support
• Pre-commit hook integration
• Command line interface
• Language server protocol (LSP) support

Usage

# Lint the current directory
ruff check .

# Lint and apply auto-fixes
ruff check --fix .

# Format code
ruff format .

# Check formatting without modifying files
ruff format --check .

# Format Python code blocks in a Markdown file
ruff format README.md

Pros

• Single tool replacing many others
• Exceptional performance
• Active development and community
• Standardized configuration via pyproject.toml
• IDE integration via language server

Cons

• Some advanced Python static analysis features are still in development
• May require an adjustment period for teams used to multiple tools