# Ruff: Python Linter and Formatter

Ruff is a fast Python linter and code formatter from [Astral](https://astral.sh/) (the makers of [uv](https://pydevtools.com/handbook/reference/uv.md) and [ty](https://pydevtools.com/handbook/reference/ty.md)). It replaces multiple Python code quality tools (like flake8, [Black](https://pydevtools.com/handbook/reference/black.md), isort, and pyupgrade) with a single binary.

{{< callout type="info" >}}
Ruff includes over 950 built-in lint rules (413 enabled by default) and can replace functionality from dozens of Python code quality tools.
{{< /callout >}}

## 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](https://pydevtools.com/handbook/reference/flake8.md), [Black](https://pydevtools.com/handbook/reference/black.md), 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 and import sorting with `ruff check`, and formatting with `ruff format`.

To get started with Ruff, see [Set up Ruff for formatting and checking your code](https://pydevtools.com/handbook/tutorial/set-up-ruff-for-formatting-and-checking-your-code.md) for a step-by-step walkthrough. For a complete guide covering rule categories, configuration, and migrating existing projects, see [Ruff: a complete guide](https://pydevtools.com/handbook/explanation/ruff-complete-guide.md).

If you need deeper static analysis beyond what lint rules provide, pair Ruff with a type checker like [mypy](https://pydevtools.com/handbook/reference/mypy.md) or [pyright](https://pydevtools.com/handbook/reference/pyright.md); for a comparison with traditional linting, see [How do Ruff and Pylint compare?](https://pydevtools.com/handbook/explanation/how-do-ruff-and-pylint-compare.md).

## 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](https://pydevtools.com/handbook/how-to/how-to-sort-python-imports-with-ruff.md))
* Code Upgrades: Modernizes Python code syntax automatically (e.g. replacing deprecated patterns with modern equivalents)
* Configuration: Uses standard [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) 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 line, block, and file suppression comments. Configuration-based [per-file ignores](https://pydevtools.com/handbook/how-to/how-to-ignore-a-ruff-rule-for-a-directory.md) suppress rules for directory or filename patterns.

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

```python
import os  # noqa: F401
```

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:

```python
# ruff: ignore[F401]
import os
import sys  # ruff: ignore[F401]
```

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

```python
# 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 must appear on its own line anywhere in the file:

```python
# ruff: noqa: F841
```

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

```python
# 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

```bash
# 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