Astral Services: The Ruff Tutorial

The Ruff Tutorial is a guided walkthrough published in Astral's documentation that covers the process of integrating Ruff's linter and formatter into a project. It points readers to the more detailed "Configuring Ruff" material for a fuller overview. The tutorial is organised into sections on getting started, configuration and integrations.

• Guided introduction to Ruff's linter and formatter
• Sections on getting started, configuration and integrations
• Configuration subsections on rule selection, ignoring errors and adding rules
• Cross-references the Configuring Ruff documentation

The tutorial begins by initialising a Python library project with uv, Astral's package manager, using `uv init --lib numbers`, then adds Ruff as a development dependency with `uv add --dev ruff`. It demonstrates running the linter through `uv run ruff check`, which flags an unused `os` import as F401, and resolves it automatically with `ruff check --fix`. The formatter is then run via `ruff format`, which reflows a `sum` call to fit the default 88-character line length. As an alternative to `uv run`, the tutorial notes that Ruff can be run after activating the project's virtual environment.

• uv init --lib numbers to create the project
• uv add --dev ruff to add Ruff
• uv run ruff check to lint
• ruff check --fix for fixable errors
• uv run ruff format to format
• Paths may be passed explicitly, e.g. ruff check src/numbers/calculate.py

The tutorial sits alongside Astral's reference documentation for the two Ruff entrypoints it exercises. `ruff check` is the primary entrypoint to the linter, accepting files or directories, searching recursively for Python files and optionally applying fixes, with enabled rules controlled by the `lint.select`, `lint.extend-select` and `lint.ignore` settings. `ruff format` is the primary entrypoint to the formatter, which formats files in place or, with `--check`, exits with a non-zero status when unformatted files are found. Ruff supports over 900 lint rules, each re-implemented in Rust as a first-party feature, and the Settings pages document top-level configuration keys and the options exposed by the Ruff Language Server.

• ruff check — linter entrypoint, with --fix and --watch options
• ruff format — formatter entrypoint, with --check mode
• Over 900 lint rules, many inspired by Flake8, isort and pyupgrade
• Top-level settings including builtins, cache-dir, exclude and extend
• Language server settings such as configuration, lineLength and fixAll

The tutorial's final section points to Ruff's integration options, which are documented separately. These include GitHub Actions, where Ruff can be run directly or through `ruff-action`, GitLab CI/CD with a codequality-compatible report, pre-commit via `ruff-pre-commit`, mdformat and Docker images. The `ruff-action` step accepts optional parameters for the Ruff version, command-line arguments and source paths.

• GitHub Actions, including astral-sh/ruff-action
• GitLab CI/CD with a codequality report
• pre-commit hooks via ruff-pre-commit
• mdformat
• Docker images such as ruff:latest and ruff:alpine

Readers following the tutorial are supported by an FAQ that explains how Ruff relates to existing tools. The FAQ states that the Ruff linter is compatible with Black out of the box provided the `line-length` setting is consistent, and that the formatter is designed as a drop-in replacement for Black, formatting more than 99.9% of lines identically on extensive Black-formatted projects such as Django and Zulip. The linter can be used as a drop-in replacement for Flake8 under stated conditions and re-implements a number of popular Flake8 plugins natively. A separate contributing guide describes how to help with Ruff, including the labels used on issues and the requirement that any use of AI follows Astral's AI policy.

• FAQ on Black, Flake8, Pylint and type-checker comparisons
• Formatter targets Black compatibility
• Contributing guide with good first issue and help wanted labels
• Separate contributing guide for ty