Python Developer Tooling Handbook – Ruff

Ruff: A Complete Guide to Python's Fastest Linter and Formatter

Tim Hopper — Wed, 06 May 2026 06:22:32 -0400

Ruff replaces flake8, Black, isort, pyupgrade, pydocstyle, and dozens of other Python code quality tools with a single binary. It re-implements over 1,000 lint rules from dozens of existing tools and runs 10-100x faster than the tools it replaces.

Astral (the team behind uv and ty) builds and maintains Ruff.

Why Ruff exists

Ruff gives Python developers a single tool for linting, formatting, import sorting, and code modernization. One dev dependency, one configuration section in pyproject.toml, one CI step. It ships as a standalone binary with no runtime dependencies, so installation is fast and there are no version conflicts to manage.

How do Ruff and Pylint compare?

Tim Hopper — Fri, 01 May 2026 06:58:47 -0400

Ruff and Pylint are Python code analysis tools with overlapping but distinct capabilities.

Core Differences

Speed and Architecture

Ruff’s Rust implementation delivers dramatically faster performance than Pylint’s Python codebase. This speed advantage becomes particularly noticeable in large codebases where Ruff can analyze files orders of magnitude faster.

Rule Coverage

While Pylint implements approximately 409 rules, Ruff now exceeds 1,000 total rules, with around 209 overlapping with Pylint’s ruleset. However, these numbers continue to change, especially as Ruff undergoes rapid development.

How to configure recommended Ruff defaults

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

This guide assumes you have a Python project set up. If you haven’t created a project yet, see the project creation tutorial before proceeding.

This guide shows how to configure Ruff with a curated set of linting rules that extend beyond the defaults. When starting a new project, it’s easier to enable a comprehensive set of rules from the beginning and selectively disable any that don’t fit the project’s needs, rather than gradually adding rules later when there’s already code to fix.

How to configure Ruff for Django

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Ruff’s default rule set knows nothing about Django. It will not flag CharField(null=True), but it will flag every long line in an auto-generated migration. This guide fixes that: enable the DJ rule set, give Ruff the per-file ignores Django’s generated code needs, and produce a configuration block that catches Django-specific bugs without burying them under noise.

This guide assumes a working Django project. Follow Set up a Django project with uv first if there isn’t one yet.

How to configure Ruff with Claude Code

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Claude Code does not run Ruff by default, so Python edits land unformatted and lint errors slip through unless you wire Ruff in yourself. Out of the box, Claude often calls bare ruff (which may resolve outside the project’s virtual environment) and skips formatting after edits. Wiring Ruff in correctly takes four layers, each with a different job.

This guide covers all four and how they stack together:

A CLAUDE.md instruction that points Claude at Ruff
The Astral plugin’s /astral:ruff skill for on-demand Ruff guidance
A PostToolUse hook that auto-formats every Python edit
A pre-commit gate that catches anything Claude missed before commit time

Prerequisites

Claude Code installed
uv installed
A Python project with Ruff added as a dev dependency (uv add --dev ruff)
jq installed if you want to use the shell version of the auto-format hook

Pick the right layer for your goal

Each layer answers a different question. Pick the ones that match what you actually need; nothing requires installing all four.

How to Enable Ruff Security Rules

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Ruff’s S rule group implements flake8-bandit security checks, catching hardcoded passwords, injection vulnerabilities, insecure hashing, and unsafe deserialization before they reach production.

Enable the Full Set

Add the S group to the project’s pyproject.toml:

[tool.ruff.lint]
extend-select = [
    "S",    # flake8-bandit security rules
]

This enables all flake8-bandit rules at once. Run the linter to see what it finds:

How to install the Astral plugins for Claude Code

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

Astral publishes an official Claude Code plugin that bundles three skills (/astral:uv, /astral:ruff, /astral:ty) and a ty language server. The skills give Claude up-to-date usage guidance for each tool, and the language server feeds live type-checking diagnostics into the conversation.

Prerequisites

Claude Code installed
uv installed (required by the ty language server)

Install the plugin for yourself

1. Add the Astral marketplace

Run this slash command inside Claude Code:

How to migrate from Black to Ruff formatter

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Ruff’s ruff format command is a drop-in replacement for Black. It follows the same formatting style, reads the same defaults (88-character lines, double quotes, space indentation), and formats 10-100x faster. Ruff also handles linting and import sorting, so the migration is often a chance to consolidate three tools (Black, flake8, isort) into one.

This guide covers translating Black’s configuration, reformatting the codebase, updating pre-commit hooks, and updating CI.

Check your starting point

Commit any pending changes. The migration reformats files, so starting from a clean working tree makes the diff easy to review.
Note your current Black version. Ruff’s formatter tracks Black’s stable style; the reformatting diff should be empty or nearly empty if your project already runs a recent Black release.

Add Ruff to the project

Add Ruff as a development dependency:

How to replace Black, isort, flake8, and pyupgrade with Ruff

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Ruff replaces Black, isort, flake8 (with its plugins), and pyupgrade with one binary and one configuration table. This guide walks through the consolidation, including the awkward case of keeping flake8 around to run one in-house custom plugin.

A typical 2010s Python project assembles its lint stack one tool at a time and ends up with config scattered across pyproject.toml, setup.cfg, .flake8, and .pre-commit-config.yaml. Ruff folds every rule set those tools provided into stable prefix codes inside a single binary. The formatter is Black-compatible and the import sorter matches isort; the UP category covers what pyupgrade did.

How to sort Python imports with Ruff

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

This guide assumes you have uv installed. If you haven’t installed uv yet, follow the installation instructions before proceeding.

This guide shows how to automatically organize and sort Python imports using Ruff:

Ruff: Python Linter and Formatter

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

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.

Ruff includes over 1,000 built-in lint rules and can replace functionality from more than 20 different Python code quality tools.

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

Set up Ruff for formatting and checking your code

Tim Hopper — Sat, 02 May 2026 08:50:33 -0400

This tutorial helps you set up Ruff to automatically format your Python code and check it for common errors and style issues.

Prerequisites

Before starting, make sure you have uv installed on your system. You can install it following the installation guide.

You do not need Python installed - uv will handle installing it automatically.

Creating a sample project

Let’s create a new project to demonstrate Ruff: