yamlruff

A fast YAML linter and fixer, written in Rust.

• ⚡️ Fast: about 28× faster than existing YAML linters and 13× faster than existing YAML fixers (measured on real-world files).
• 🔧 Lint and fix in one tool: yamlruff lint reports, yamlruff fix repairs, with one shared configuration.
• 🛡️ Safe fixes: every fix is checked to leave the loaded data unchanged; files with syntax errors are never touched.
• 📏 23 built-in rules: whitespace, indentation, flow collections, comments, quoting, keys and anchors.
• 🐍 Installable via pip or uv, as a prebuilt binary: no Python dependencies, no Rust toolchain.
• 🛠️ pyproject.toml support: configure under [tool.yamlruff], or in a .yamlruff file.
• 🧩 Shareable configs with extends, per-rule ignore, and inline # yamlruff disable comments.
• 🤖 CI-friendly: --check for fixes, -f github annotations, and clear exit codes.

yamlruff is an independent project, not affiliated with Astral or the ruff project.

Table of Contents

• Getting Started
• Installation
• Usage
• Configuration
• Rules
• Fixing
• Continuous integration
• Contributing
• Support
• License

Getting Started

With uv, no install needed:

uvx yamlruff lint .        # find problems
uvx yamlruff fix --diff .  # preview the fixes
uvx yamlruff fix .         # apply them

Or with pip:

pip install yamlruff
yamlruff lint .            # find problems
yamlruff fix --diff .      # preview the fixes
yamlruff fix .             # apply them

For example, given service.yml:

name:   web
enabled: yes
ports: [ 80,443 ]

yamlruff lint service.yml reports the missing ---, the extra spaces after the colon, the yes, the spaces inside the brackets and the missing space after the comma. yamlruff fix repairs the layout problems right away and leaves the yes for --unsafe-fixes, because rewriting it to true changes what some YAML loaders read.

Installation

uv tool install yamlruff     # or: pipx install yamlruff / pip install yamlruff

Run it once without installing with uvx yamlruff …. Check the install with yamlruff --version.

Prebuilt wheels exist for macOS (Intel and Apple Silicon) and Linux (glibc and musl; x86_64 and aarch64). On other platforms pip builds from the source distribution and needs Rust.

Usage

yamlruff lint [PATHS]...           # report problems ('-' reads stdin; default '.')
yamlruff fix [PATHS]...            # rewrite files, then report what is left
yamlruff rule [ID]                 # list the rules, or document one

Configuration

yamlruff reads .yamlruff (or .yamlruff.yaml / .yamlruff.yml) from the current directory and then upward, or a [tool.yamlruff] table in pyproject.toml. Without either, it uses the default preset; extends: relaxed is more lenient.

# .yamlruff
extends: default
rules:
  line-length: {max: 120}
  truthy: {check-keys: false}     # keep `on:` as a key in GitHub Actions
  indentation: {spaces: 2, indent-sequences: true}
  trailing-spaces: disable
ignore: |
  dbt_packages/
  target/

# pyproject.toml
[tool.yamlruff.rules]
line-length = { max = 120 }

Other top-level keys: yaml-files (which files count as YAML), ignore-from-file, respect-gitignore (default false), locale, and the fix: section described under Fixing. Turn rules off inside a file with comments:

# yamlruff disable-line rule:line-length
# yamlruff disable rule:truthy
# yamlruff enable rule:truthy
# yamlruff disable-file

Rules

23 rules; yamlruff rule <id> shows the options, defaults and what the fix does.

Fix: safe changes layout only; unsafe needs --unsafe-fixes. A few cases within a rule (for example .nan in float-values, or undeclared aliases) have no fix and only report. Rules that report as error fail the run, warning rules only with --strict.

Fixing

yamlruff fix applies the fix that belongs to each problem, using the rule's own options, so after a fix lint has nothing left to report that could have been fixed automatically. After every round it checks that the document still loads to the same data, and drops any fix that would change it. Some problems have no safe automatic fix (a duplicated key with different values, a line that cannot be wrapped) and stay in the report.

Pure style choices that no rule expresses go in a fix: section:

fix:
  sequence-style: flow         # keep | flow | block
  none-representation: empty   # keep | empty | null | '~' | Null | NULL
  whitelines: 1                # blank lines between content
  comments-whitelines: 1       # blank lines before a comment
  section-whitelines: 1        # blank lines around top-level sections
  join-multiline: false        # put multi-line scalars on one line when they fit
  simplify-block-headers: false
  unsafe-fixes: false
  unfixable: []                # rule ids whose fixes are never applied

Continuous integration

yamlruff lint --strict .       # fail the build on any problem
yamlruff fix --check .         # fail if formatting would change anything
yamlruff lint -f github .      # annotate the pull request in GitHub Actions

Exit codes for lint: 0 clean, 1 errors, 2 warnings only (with --strict).

Contributing

Bug reports, ideas and pull requests are welcome. See CONTRIBUTING.md for how to build, test and release.

Support

Open an issue on the repository with the yamlruff --version, the command you ran, and a minimal YAML file that shows the problem.

License

This repository is licensed under the GPL-3.0-or-later License.