yamllint review
yamllint checks YAML text for parser errors, duplicate keys, indentation, trailing spaces, line length, quoting, truth-like values, and other source conventions. It reports every configured problem with its file, line, column, severity, and rule ID through a CLI or Python iterator. It does not know Kubernetes kinds, GitHub Actions fields, or an application's schema. Version 1.38.0 adds Python 3.14, removes Python 3.9, changes `yaml-files` and `ignore` to follow gitignore behavior, and adds `quote-type: consistent` to the quoted-strings rule.
yamllint 1.38.0 installed in 0.5 seconds, used 4 MB across 3 packages, and returned 0 audit findings in our sandbox. Add it for YAML syntax and source-policy checks, then pair it with a domain validator when fields and value types matter.
We installed it
| Install | ✓ · 0.5s | 3 packages on disk · 4 MB |
| Import | ✓ | import yamllint in 0.02s · pure Python · requires Python >=3.10 |
| Known vulns | 0 | (pip-audit) |
Answers from our run
Does yamllint install cleanly?
Yes. In a fresh container with an empty cache, pip install yamllint finished in 0.5s, leaving 3 packages and 4 MB on disk. pip-audit reported no known vulnerabilities.
What does yamllint need to run?
Python >=3.10, and nothing compiled: it is pure Python. In our run import yamllint succeeded in 0.02s.
yamllint or strictyaml: which should you use?
strictyaml: Choose it when Python should parse a deliberately restricted YAML subset and validate values against an application schema. yamllint 1.38.0 installed in 0.5 seconds, used 4 MB across 3 packages, and returned 0 audit findings in our sandbox.
When should you not use yamllint?
The goal is validating Kubernetes, OpenAPI, GitHub Actions, or application fields. yamllint checks YAML syntax and presentation, not a domain schema.
Use it if
- People edit YAML in the repository and CI should catch duplicate keys, invalid indentation, and stray whitespace.
- One `.yamllint` file should drive local commands, pre-commit, editor integrations, and CI annotations.
- Style preferences should remain warnings while syntax and selected mistakes block the build.
- A Python program needs structured lint problems for YAML text without loading application objects.
- The goal is validating Kubernetes, OpenAPI, GitHub Actions, or application fields. yamllint checks YAML syntax and presentation, not a domain schema.
- Files should be rewritten automatically. yamllint reports locations and rule names but has no formatter or fix mode.
- The toolchain is fixed on Python 3.9. Version 1.38.0 requires Python 3.10 or newer.
- GPL-3.0-or-later is unacceptable for the planned distribution. PyPI now declares that expression, while our package probe did not detect a license value.
- Most inputs contain Helm, Jinja, or another placeholder syntax before they become YAML. Parser failures or broad exclusions can make this the wrong stage to lint.
Setup reality
We installed yamllint 1.38.0 in a clean Python 3.12 Bookworm sandbox. The operation finished in 0.5 seconds, left 3 packages, and occupied 4 MB. The package declares 8 direct dependencies, requires Python 3.10 or newer, and is pure Python. import yamllint completed in 0.02 seconds, and pip-audit found 0 known vulnerabilities. There is no py.typed marker. Our package probe did not identify a license, although current PyPI metadata says GPL-3.0-or-later.
Without -c, yamllint searches for .yamllint, .yamllint.yaml, or .yamllint.yml, including parent directories. Begin with extends: default or extends: relaxed, then record intentional changes. GitHub Actions needs a decision around the truthy rule because on is a workflow key but resembles a YAML 1.1 boolean. Narrow that exception; disabling a whole workflow hides unrelated duplicate-key and whitespace findings.
CI exit behavior is easy to misread. Normal mode returns failure for errors and permits warnings. --strict also fails on warnings, while --no-warnings suppresses them. Parsable and GitHub annotation formats support automated consumers. Run --list-files before trusting a green job, particularly after upgrading to 1.38.0, because its gitignore-compatible matching changed which paths yaml-files and ignore select.
Inline directives can disable one line, a block, a file, or named rules. They help with a certificate or unavoidable long URL, but each directive creates a lasting blind spot. Put generated and vendored trees in top-level ignores. Prefer a per-rule ignore if only quoting or line length is unsuitable. After yamllint, run the relevant schema validator whenever an unknown field or wrong value type can break deployment.
Patterns
Check named files or a directory lint-files-and-tree
yamllint deploy.yaml .github/workflows/ci.yml
yamllint .
printf '%s\n' 'name: value' | yamllint -Directory scans obey yaml-files and ignore patterns. Use --list-files to inspect the selected set.
Create a project configuration define-repository-policy
# .yamllint
---
extends: default
rules:
document-start: disable
line-length:
max: 120
level: warning
indentation:
spaces: 2
indent-sequences: consistentKeep a style dispute at warning level when it should remain visible without blocking deployment.
Handle the GitHub Actions `on` key allow-actions-on-key
# .yamllint
---
extends: default
rules:
truthy:
check-keys: falseThis disables truthy checks for every mapping key, not only `on`; truthy values remain checked.
Set CI warning behavior choose-warning-exit-code
yamllint . # only errors fail
yamllint --strict . # warnings fail too
yamllint --no-warnings . # warnings are omitted--strict promotes warnings into a failing status, while --no-warnings hides them.
Annotate a GitHub workflow emit-github-annotations
- name: Lint YAML
run: |
pip install yamllint==1.38.0
yamllint --format github --strict .Pin the CLI so path-selection or rule changes arrive through a reviewed dependency update.
Ignore generated and vendored paths exclude-generated-yaml
# .yamllint
---
extends: default
ignore: |
/vendor/
/charts/**/templates/
*.generated.yaml
!/charts/values.yamlVersion 1.38.0 follows gitignore matching here. Confirm negations and anchored directories with --list-files.
Relax only line length in docs ignore-rule-for-path
# .yamllint
---
extends: default
rules:
line-length:
max: 100
ignore: |
/docs/A rule-level ignore retains parsing, duplicate-key, indentation, and whitespace checks for the same files.
Suppress one named rule disable-specific-finding
url: https://example.com/a/very/long/path # yamllint disable-line rule:line-length
# yamllint disable rule:comments
legacy: value#fixture
# yamllint enableName the rule so other problems on that line or block still appear.
Lint staged YAML run-pre-commit-hook
repos:
- repo: https://github.com/adrienverge/yamllint
rev: v1.38.0
hooks:
- id: yamllint
args: [--strict, -c, .yamllint]The hook checks selected staged files; keep a full-tree CI command for tracked files outside that selection.
Read problems through the Python API collect-python-findings
from yamllint import linter
from yamllint.config import YamlLintConfig
config = YamlLintConfig(file='.yamllint')
with open('deploy.yaml') as stream:
for problem in linter.run(stream, config, filepath='deploy.yaml'):
print(problem.line, problem.column, problem.level, problem.rule)Pass filepath so path-based ignore policy and diagnostic names work with the opened stream.
Choose one quote style per file enforce-consistent-quotes
# .yamllint
---
extends: default
rules:
quoted-strings:
quote-type: consistent
required: only-when-neededquote-type: consistent was added in 1.38.0 and can be noisy on generated or templated YAML.
Audit lint coverage list-selected-files
yamllint --list-files . | sortReview this list after ignore or yaml-files changes; a green scan says little if intended manifests were never selected.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| strictyaml | PyPI | Choose it when Python should parse a deliberately restricted YAML subset and validate values against an application schema. |
| yamale | PyPI | Choose it when YAML documents need declarative type and field validation after parsing. |
| ruyaml | PyPI | Choose it when Python must parse and round-trip YAML while preserving comments, rather than linting repository style. |
More utils guides
lru-cache · ajv · type-fest · p-limit · find-up · js-yaml · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.