yamllint

library1.38.0pypypi✓ verified 24d ago

yamllint is a linter for YAML files written in Python, version 1.38.0. It checks not only for syntax validity but also for common weirdnesses like key repetition and cosmetic issues such as line length, trailing spaces, and indentation. The project is actively maintained with regular releases.

testing devops serialization

pip install yamllint

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · YAMLLINT

yamllint

testingpythonv1.38.0

Install

1.8s avg

Import

231ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.38.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.234s · 20.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.228s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YamlLintConfig

✓ from yamllint.config import YamlLintConfig

linter

✓ from yamllint import linter

LintProblem

✓ from yamllint.linter import LintProblem

Represents a detected linting issue; returned by `linter.run`.

This quickstart demonstrates how to programmatically lint a YAML string using `yamllint`. It creates a `YamlLintConfig` and then uses `linter.run` with an `io.StringIO` object to process the YAML content, iterating over any `LintProblem` objects found.

import io from yamllint.config import YamlLintConfig from yamllint import linter yaml_content = """ key: value another_key: with_trailing_spaces nested: item """ # Use a default configuration or load a custom one config_string = "extends: default\nrules:\n trailing-spaces: enable\n indentation: enable" conf = YamlLintConfig(content=config_string) # Lint the YAML content from a string buffer problems = linter.run(io.StringIO(yaml_content), conf) found_issues = [] for p in problems: found_issues.append(f"Line {p.line}, Column {p.column}: {p.desc} (Rule: {p.rule})") if found_issues: print("YAML linting issues found:") for issue in found_issues: print(issue) else: print("No YAML linting issues found.")

yamllint --version

Debug

Known issues

breakingyamllint has progressively dropped support for older Python versions. As of 1.38.0, Python 3.9 is no longer supported, and Python 3.8 was dropped in 1.36.0. Users on older Python environments will need to upgrade their Python version or use an older yamllint version.

fix

Upgrade Python to 3.10+ or pin `yamllint` to an older compatible version.

affects: <1.38.0 (for Python 3.9+), <1.36.0 (for Python 3.8+)

gotchaBy default, the `yamllint` CLI exits with code 1 only if errors are found, not warnings. This can lead to CI/CD pipelines passing silently even with warnings. To make warnings also cause a non-zero exit code, use the strict mode.

fix

Run `yamllint` with the `--strict` (or `-s`) option in CI/CD environments: `yamllint --strict .`

affects: All versions

gotchayamllint automatically discovers and loads configuration files named `.yamllint`, `.yamllint.yaml`, or `.yamllint.yml` in the current working directory or any parent directory. This implicit loading can lead to unexpected linting rules being applied if a configuration file exists upstream that you are unaware of or did not intend to use.

fix

Explicitly specify a configuration file using the `-c` option (`yamllint -c /path/to/myconfig.yaml file.yaml`) or disable automatic config search for specific use cases. Be aware of your project's directory structure for `.yamllint` files.

affects: All versions

breakingThe API for `linter.run` experienced a change in version 1.35.0 regarding how file ignoration was handled, which was then reverted in 1.35.1. If you programmatically interact with `linter.run` and rely on specific file path handling or ignoration behavior, this version range could introduce unexpected results.

fix

Avoid `yamllint` version 1.35.0 if programmatic file ignoration is critical; upgrade to 1.35.1 or newer, or downgrade to 1.34.x or older.

affects: 1.35.0

Errors

Common errors & fixes

yamllint: command not found

The directory where pip installed the `yamllint` executable is not included in your system's PATH environment variable.

fix

Run yamllint using `python -m yamllint <file.yaml>` or add the pip binaries directory (e.g., `~/.local/bin` on Linux/macOS) to your system's PATH.

yamllint: error: Invalid config file: <path/to/.yamllint>

The specified `.yamllint` configuration file contains invalid YAML syntax, such as duplicate keys, incorrect indentation, or an unsupported structure.

fix

Review the `.yamllint` file for syntax errors, ensuring it's valid YAML and conforms to the `yamllint` configuration specification.

yamllint: error: No such option: --<some-option>

You are attempting to use a command-line option that does not exist, is misspelled, or is deprecated for your installed `yamllint` version.

fix

Run `yamllint --help` to see the list of valid options, or consult the `yamllint` documentation for the correct command-line arguments.

ModuleNotFoundError: No module named 'yamllint'

The `yamllint` Python package is not installed in the active Python environment where your script or application is attempting to import it.

fix

Install the package using pip: `pip install yamllint`.

Upgrade

Version history

1.38.0latest on PyPI · released Jan 13, 2026

Audit

Dependencies

pyyamlrequiredCore dependency for YAML parsing.

pathspecrequiredUsed for `.gitignore`-style path matching in configuration. Requires `>=1.0.0` since yamllint 1.38.0.

Agent activity

40 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/adrienverge/yamllint ↗

packagehttps://pypi.org/project/yamllint/ ↗

docshttps://yamllint.readthedocs.io ↗