ruff-format
Format Python code automatically
TLDR
Format given files or directories in-place
Print which files would have been modified and return a non-zero exit code if there are files to reformat, and zero otherwise
Print what changes would be made without modifying the files
SYNOPSIS
ruff format [OPTIONS] [FILES_OR_DIRECTORIES...]
ruff format [OPTIONS] --stdin
PARAMETERS
-c, --config
Specify a configuration file or directory containing a pyproject.toml.
--check
Check for formatting violations without writing changes.
--diff
Print a diff of formatting changes instead of applying them.
--write
Write changes to disk (default behavior for files).
--line-length
Set the preferred maximum line length for formatting.
--indent
Set the preferred indentation style (e.g., spaces, tabs).
--target-version
Specify the target Python version for compatibility.
--exclude
Exclude files or directories matching the pattern from formatting.
--stdin-filename
When formatting stdin, use this filename for context.
--respect-gitignore
Honor .gitignore files for path exclusion during formatting.
--verbose
Enable verbose output for more detailed information.
--quiet
Disable all messages except for errors during execution.
--preview
Enable preview mode to opt-in to experimental formatting changes.
--show-files
Display the list of files that Ruff will attempt to format.
--isolated
Disregard all configuration files (e.g., pyproject.toml).
DESCRIPTION
The ruff format command is an exceptionally fast and opinionated Python code formatter, part of the larger `ruff` ecosystem. Written in Rust, it aims to provide a high-performance alternative to traditional formatters like `Black`. It automatically re-formats Python source code to adhere to a consistent style, primarily following `PEP 8` and `Black`'s established conventions, ensuring code uniformity across projects. Its design emphasizes speed and correctness, making it ideal for large-scale codebases and CI/CD environments.
The command can process individual files, entire directories, or standard input. It offers various modes, including checking for formatting violations without applying changes (`--check`), printing diffs (`--diff`), or performing in-place modifications (`--write`, which is default for files). By integrating `ruff format` with the `ruff` linter, developers can use a single, efficient tool for both code quality analysis and style enforcement, significantly streamlining Python development workflows. Its configuration is typically managed through a `pyproject.toml` file, allowing for project-specific settings.
CAVEATS
The `ruff format` command is designed to be highly opinionated, similar to `Black`, meaning its customization options are intentionally limited. While this promotes consistency, it may not suit projects requiring highly specific or non-standard formatting styles. Its formatting rules, particularly those in "preview" mode, are still under active development and may evolve in future releases, potentially leading to slight changes in output. Ensure you understand its default behavior before fully adopting it, especially for existing large codebases.
CONFIGURATION VIA PYPROJECT.TOML
`ruff format` primarily uses a `pyproject.toml` file for configuration. Settings related to formatting (e.g., line length, indentation style, target Python version) are defined within the `[tool.ruff.format]` section, or globally in `[tool.ruff]`. This allows for project-wide consistency without relying on command-line flags for every invocation.
PERFORMANCE ADVANTAGES
A standout feature of `ruff format` is its remarkable speed. Leveraging Rust, it can format Python codebases orders of magnitude faster than Python-based formatters like `Black`. This makes it particularly efficient for large projects, pre-commit hooks, and CI/CD pipelines, where performance is a critical factor for rapid feedback and build times.
HISTORY
The `ruff` project, from which `ruff format` originates, was introduced by Caleb Hattingh in late 2022. It rapidly gained traction in the Python community due to its unprecedented speed, achieved by being written entirely in Rust. Initially focused solely on linting capabilities, `ruff` evolved to incorporate formatting. The `ruff format` subcommand was developed as a direct competitor to existing Python formatters like `Black` and `isort`, aiming to provide a unified, significantly faster solution for code style enforcement. Its development is ongoing, with a strong emphasis on performance and feature parity with established tools.