The Ruff Formatter — Python code formatter in the Ruff CLI

`ruff format` is the primary entrypoint to the formatter. It accepts a list of files or directories and formats all discovered Python files, recursing into subdirectories. Running it against a path formats the file or directory in place, while `ruff format --check` avoids writing formatted files back and exits with a non-zero status code when unformatted files are detected. The full list of supported options is available via `ruff format --help`.

• ruff format — format all files in the current directory
• ruff format path/to/code/ — format a directory and its subdirectories
• ruff format path/to/file.py — format a single file
• ruff format --check — report unformatted files without writing

The formatter is intended to emit near-identical output when run over existing Black-formatted code, and adheres to Black's stable code style. When run over extensive Black-formatted projects such as Django and Zulip, more than 99.9% of lines are formatted identically. When run over code that has not been formatted with Black, the formatter makes some different decisions, particularly around the treatment of end-of-line comments. The documentation notes that projects migrating from Black should expect a few differences on the margins, and that the formatter is not intended to be used interchangeably with Black on an ongoing basis.

The stated initial goal of the Ruff formatter is not to innovate on code style but on performance, and to provide a unified toolchain across Ruff's linter, formatter and future tools. Targeting Black compatibility is described as a way of making formatter adoption minimally disruptive for most projects, given Black's popularity in the Python ecosystem. Like Black, the formatter does not support extensive code style configuration, though it does allow configuration of quote style, indent style and line endings.

The formatter is configured through the same files as the rest of Ruff: a `pyproject.toml`, `ruff.toml` or `.ruff.toml` file, using the `[tool.ruff.format]` or `[format]` table. Default settings mirror Black's behaviour, including double quotes for strings, indentation with spaces, respect for magic trailing commas and automatic line-ending detection. Shared settings such as `line-length` (default 88), `indent-width` (default 4) and `exclude` apply to both the linter and the formatter.

• quote-style — default "double"
• indent-style — default "space"
• skip-magic-trailing-comma — default false
• line-ending — default "auto"
• docstring-code-format — disabled by default
• docstring-code-line-length — default "dynamic"

The formatter can format code examples embedded in docstrings when `docstring-code-format` is enabled, with a separate line-length setting for those snippets. Several embedded formats are recognised. The formatter can also format Python code blocks inside Markdown files, using the same settings applied to regular Python files; other parts of Markdown files are left untouched.

• Python doctest format
• CommonMark fenced code blocks
• reStructuredText literal blocks
• reStructuredText code-block and sourcecode directives
• Python code blocks in Markdown files

The formatter is one half of the Ruff CLI, the other being the linter invoked with `ruff check`. The documentation notes that certain lint rules conflict with the formatter, including tab-indentation (W191), indentation-with-invalid-multiple (E111), over-indented (E117), incorrect-blank-line-before-class (D203), docstring-tab-indentation (D206), triple-single-quotes (D300) and bad-quotes-inline-string (Q000). The tutorial demonstrates running `ruff check --fix` followed by `ruff format` on a project, with the formatter rewriting a multi-line call to fit the default 88-character line length.

The Ruff Language Server exposes the formatter in editors, able to format an entire Python document or a selected range of lines. In VS Code, the Ruff extension provides a Ruff: Format Document command, and a Format Document command for Markdown files that formats embedded Python code blocks; range formatting is not supported for Markdown. The language server reads an existing `pyproject.toml` or `ruff.toml` file to configure both the linter and the formatter, and editor settings such as inline JSON configuration can supply `format` options like `quote-style`. Setup instructions are published for a range of editors.

• VS Code
• Neovim and Vim
• Helix
• Kate
• Sublime Text
• PyCharm
• Emacs
• TextMate
• Zed