yaml-lint-rs

yaml-lint-rs

A fast YAML linter written in Rust, inspired by yamllint.

Built with Claude Code and Cursor.

Why yaml-lint-rs?

• ⚡ 20-60x faster than Python yamllint (see benchmarks)
• 📦 Single binary - no runtime dependencies required
• 🔧 Drop-in replacement - compatible with yamllint config format
• 🦀 Memory safe - written in Rust

Features

• ✅ Fast and efficient YAML linting
• ✅ Parallel linting using all CPU cores (-j/--jobs)
• ✅ Auto-fix support for common issues (--fix)
• ✅ Multiple output formats (standard, colored, parsable)
• ✅ Configurable rules with preset configurations
• ✅ Support for .yamllint configuration files
• ✅ Directory traversal for batch linting
• ✅ Exit codes for CI/CD integration

Performance

yaml-lint-rs is significantly faster than Python yamllint:

Benchmarks run on Apple M1, macOS. Results may vary. See benchmarks/ for reproduction.

Installation

From crates.io (Recommended)

cargo install yaml-lint

Homebrew (macOS/Linux)

brew tap hiromaily/tap
brew install yaml-lint

From Source

Requires Rust 1.85+ (install from rustup.rs):

git clone https://github.com/hiromaily/yaml-lint-rs.git
cd yaml-lint-rs
cargo build --release
# The binary will be at ./target/release/yaml-lint

Usage

Basic usage

# Lint a single file
yaml-lint file.yaml

# Lint multiple files
yaml-lint file1.yaml file2.yaml

# Lint all YAML files in a directory
yaml-lint src/

# Lint with specific config file
yaml-lint -c .yamllint file.yaml

Output formats

# Standard human-readable output (default in non-TTY)
yaml-lint file.yaml

# Colored output (default in TTY)
yaml-lint -f colored file.yaml

# Machine-parsable output
yaml-lint -f parsable file.yaml

Color control

# Auto-detect based on terminal (default)
yaml-lint --color auto file.yaml

# Always use colors
yaml-lint --color always file.yaml

# Never use colors
yaml-lint --color never file.yaml

Colors are automatically enabled when output is to a terminal. The NO_COLOR environment variable is respected (see https://no-color.org/).

Presets

# Use default preset (strict)
yaml-lint -d default file.yaml

# Use relaxed preset
yaml-lint -d relaxed file.yaml

Auto-fix

# Fix all auto-fixable issues
yaml-lint --fix file.yaml

# Fix all files in a directory
yaml-lint --fix src/

# Dry-run: show what would be fixed without making changes
yaml-lint --dry-run file.yaml

Fixable Rules:

• trailing-spaces - Removes trailing whitespace
• new-line-at-end-of-file - Adds missing newline at end of file
• empty-lines - Removes excess blank lines

Parallel linting

# Auto-detect thread count (default — uses all logical CPUs)
yaml-lint src/

# Explicit thread count
yaml-lint -j 4 src/

# Single-threaded (useful for debugging)
yaml-lint -j 1 src/

Options

# Treat warnings as errors
yaml-lint --strict file.yaml

# List files that would be linted
yaml-lint --list-files src/

Configuration

Create a .yamllint or .yamllint.yml file in your project root:

# Extend a preset
extends: default

# Configure individual rules
rules:
  trailing-spaces: error
  line-length:
    max: 120
  document-start: disable
  indentation:
    spaces: 2

# Ignore patterns
ignore: |
  /vendor/
  *.generated.yaml

Available Presets

default (strict)

• All rules enabled as errors
• Suitable for production code

relaxed

• Most rules as warnings
• More permissive for development

Implemented Rules

✅ Phase 1 (Complete)

1. trailing-spaces - Detects whitespace at line endings

   • Level: Error
   • No configuration

2. line-length - Enforces maximum line length

   • Level: Error
   • Options: max (default: 80)

3. document-start - Requires or forbids --- at document start

   • Level: Disable (by default)
   • Options: present (true/false)

4. colons - Validates spacing around colons in mappings

   • Level: Error
   • Options: max-spaces-before (0), max-spaces-after (1)

5. key-duplicates - Prevents duplicate keys in mappings

   • Level: Error
   • Critical for YAML correctness

6. indentation - Validates consistent indentation

   • Level: Error
   • Options: spaces (2/4/consistent), indent-sequences

7. new-line-at-end-of-file - Requires newline at end of file

   • Level: Error
   • POSIX standard compliance

8. empty-lines - Limits consecutive blank lines

   • Level: Error
   • Options: max (default: 2), max-start (0), max-end (0)

9. hyphens - Controls spacing after list item hyphens

   • Level: Error
   • Options: max-spaces-after (default: 1)

10. comments - Enforces consistent comment formatting

    • Level: Error
    • Options: require-starting-space, min-spaces-from-content

11. truthy - Restricts boolean representations (YAML 1.1 vs 1.2)

    • Level: Warning
    • Options: allowed-values, check-keys

📋 Future Rules

Additional rules planned for full yamllint compatibility:

• new-lines, empty-values
• braces, brackets, commas
• comments-indentation, document-end
• float-values, octal-values, quoted-strings, key-ordering

Exit Codes

• 0: Success (no errors, or only warnings without --strict)
• 1: Errors detected
• 2: Warnings detected with --strict flag

Examples

Example 1: Trailing spaces

# Bad
key: value

# Good
key: value

Example 2: Line length

# Bad (> 80 characters)
key: this is a very long value that exceeds the maximum line length of eighty characters

# Good
key: shorter value
# or use multiline
key: |
  this is a very long value
  split across multiple lines

Roadmap

• Phase 1: Core infrastructure + 6 priority rules
• Phase 2: Additional output formats, directives, more rules
• Phase 3: Full yamllint parity (23 rules)
• Phase 4: Performance optimizations, parallel linting
• Phase 5: Editor integration (LSP?)

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Acknowledgments

Inspired by yamllint by Adrien Vergé.