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, defaulting to the current directory when no path is given. As with Black, running `ruff format /path/to/file.py` rewrites the file in place, while `ruff format --check /path/to/file.py` writes nothing and instead 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 targets Black compatibility so that adoption is minimally disruptive for existing projects. It is intended to emit near-identical output when run over Black-formatted code: across extensive Black-formatted projects such as Django and Zulip, more than 99.9% of lines are formatted identically. When migrating an existing project from Black to Ruff, a few differences at the margins should be expected, while the majority of code remains unchanged. Run over code that has not been formatted by Black, the formatter makes some different decisions, particularly around end-of-line comments.

• Drop-in replacement for Black
• > 99.9% of lines identical on Black-formatted projects
• Adheres to Black's stable code style
• Larger deviations expected on non-Black-formatted code

The stated initial goal of the 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. Like Black, it does not support extensive code style configuration; unlike Black, it allows configuration of quote style, indent style and line endings, among others. Although it is a drop-in replacement, it is not intended to be used interchangeably with Black on an ongoing basis.

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. The configuration strategy and semantics are identical whether Ruff is used as a linter, a formatter or both. Default settings mirror Black, including a line length of 88, four-space indentation, double quotes for strings, respect for magic trailing commas and automatic line-ending detection. Formatting of code examples inside docstrings is controlled by `docstring-code-format`, with `docstring-code-line-length` setting the line length limit used for those snippets.

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

The formatter can auto-format code examples embedded in docstrings, covering the Python doctest format, CommonMark fenced code blocks, reStructuredText literal blocks, and reStructuredText `code-block` and `sourcecode` directives. It can also format Python code blocks within Markdown files, leaving other parts of those files untouched. The documentation additionally covers format suppression, lint rules that conflict with the formatter, exit codes and the style guide, including intentional deviations, preview style and f-string formatting.

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

Formatting is exposed through the Ruff Language Server, which can format an entire document or a selected range of lines. The VS Code extension provides a Ruff: Format Document command, and range formatting can be triggered by selecting lines and choosing Format Selection. Markdown code-block formatting is available through the same Format Document command, though range formatting is not supported for Markdown files. The language server can read an existing `pyproject.toml` or `ruff.toml` file to configure the linter and formatter, or take settings supplied by the editor, with editor-specific settings taking precedence over the `ruff.configuration` field and then project configuration files.

• Ruff: Format Document command in VS Code
• Range formatting for Python documents
• Markdown code-block formatting (no range formatting)
• Setup guides for VS Code, Neovim, Vim, Helix, Kate, Sublime Text, PyCharm, Emacs, TextMate and Zed

The Ruff tutorial walks through adding Ruff to a project and running both the linter and the formatter. After adding Ruff as a development dependency, `ruff format` reformats files to fit the configured line length — in the tutorial example, a multi-line `sum` call is collapsed to fit within the default 88-character limit. Ruff runs in the current directory by default, but specific paths can be passed on the command line.