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?.

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
• Import Sorting: Orders and groups Python imports systematically
• 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 900 lint rules drawn from dozens of existing tools:

• 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: Add # noqa: {code} to the end of a line to suppress a specific rule for that line:

x = 1  # noqa: 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: Add # ruff: noqa: {code} near the top of a file to suppress a rule for the entire file:

# ruff: noqa: 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 .

Advantages

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

Limitations

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

Related Handbook Pages

• Set up Ruff for formatting and checking your code (Tutorial)
• How to configure recommended Ruff defaults
• How to sort Python imports with Ruff
• How do Ruff and Pylint compare?

Learn More

• Set up Ruff for formatting and checking your code (Tutorial)
• How to configure recommended Ruff defaults
• How to sort Python imports with Ruff
• How do Ruff and Pylint compare?
• ruff Documentation
• GitHub Repository
• Configuration Guide
• Rules Reference