yamlguard

Check your YAML files before you commit or deploy them. yamlguard catches syntax errors and style issues, and can scan supported infrastructure files for security problems with Checkov.

Install the yamlguard CLI from PyPI, or use the Docker image pooyanazad/yaml-checker. Both run the same validator; Docker includes Checkov. The current Docker release uses the earlier image name; future releases will use pooyanazad/yamlguard.

Install and run

Python

Requires Python 3.9 or newer. Create a virtual environment so the installation stays separate from your system Python.

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install yamlguard

Windows — Command Prompt:

py -m venv .venv
.venv\Scripts\activate
python -m pip install yamlguard

In PowerShell, activate the environment with .\.venv\Scripts\Activate.ps1 instead.

Then check a file:

yamlguard config.yaml

The base installation checks syntax with PyYAML and style with yamllint. To add security scanning, install the optional extra in the same environment:

python -m pip install "yamlguard[security]"
yamlguard deployment.yaml

Checkov checks supported infrastructure formats, such as Kubernetes manifests. Without Checkov, syntax and style checks still run, with a warning that security scanning was skipped.

Docker

With Docker installed, open a terminal in the folder containing your YAML files and run:

Linux / macOS:

docker run --rm -v "$(pwd):/data:ro" pooyanazad/yaml-checker:v3.5.0-20261011 config.yaml

Windows — PowerShell:

docker run --rm -v "${PWD}:/data:ro" pooyanazad/yaml-checker:v3.5.0-20261011 config.yaml

Windows — Command Prompt:

docker run --rm -v "%cd%:/data:ro" pooyanazad/yaml-checker:v3.5.0-20261011 config.yaml

These commands mount your current folder read-only at /data. Use paths within that folder, such as config.yaml or ./configs/. Files must be readable by the container's non-root user.

Images support linux/amd64 and linux/arm64. The examples use the published 3.5.0 image. Use the Docker image and versioned tag shown under Latest release when choosing another release.

Everyday examples

yamlguard config.yaml                        # Check one file
yamlguard config.yaml deployment.yml         # Check several files
yamlguard ./configs/                         # Check all .yaml and .yml files recursively
yamlguard "./configs/**/*.yaml"              # Let yamlguard expand the pattern
yamlguard ./configs/ --no-security            # Run syntax and style checks only
yamlguard deployment.yaml --timeout 60       # Limit each validator subprocess to 60 seconds

With Docker, pass these same arguments after the image name. For example, replace config.yaml in the Docker command with ./configs/ --no-security.

Run yamlguard --help for all options. You can also run the CLI as python -m yamlguard. Missing paths are skipped with a warning; the command fails if no files remain.

Reports and exit codes

Text output is the default. For CI or other tools, export a report:

yamlguard ./configs/ --format json > results.json
yamlguard ./configs/ --format junit > test-results.xml
yamlguard ./configs/ --format sarif > results.sarif

JSON returns one object for one file or an array for several files. JUnit XML works with test-report viewers; SARIF 2.1.0 works with compatible code-scanning tools. Upload reports through your CI configuration.

In version 3.5.0 and newer, machine-readable reports go to stdout and warnings go to stderr.

Syntax errors are Critical. Lint errors are Medium and warnings are Low, so lint findings alone do not fail the command. Checkov findings without a severity default to High.

Project links

Releases · Report an issue · Contributing · Maintainer release guide

Latest release

v3.5.1-20261011 — 2026-10-11

Changes since v3.5.0-20261011 (7 non-merge commits).

• Build and maintenance: 2 commit(s).
• Fixes: 3 commit(s).
• Documentation: 2 commit(s).

Full changelog

Docker image: pooyanazad/yamlguard:v3.5.1-20261011