AWS CloudFormation Linter (cfn-lint)

1.47.1 · active · verified Tue Mar 31

cfn-lint is an open-source static analysis tool developed by AWS that checks CloudFormation templates (YAML/JSON) for potential errors, adherence to AWS best practices, and valid resource configurations. It validates templates against the AWS CloudFormation resource provider schemas and additional checks, aiming to catch issues before deployment. The project is actively maintained with frequent updates, often including new CloudFormation schemas and linting rules.

Warnings

breaking Python 3.9 support has been removed as of cfn-lint v1.47.0. Users on Python 3.9 or older must upgrade their Python environment to 3.10 or newer.
Fix: Upgrade Python to version 3.10 or newer. (e.g., `pyenv install 3.10.12 && pyenv global 3.10.12`)
breaking cfn-lint v1 introduced major breaking changes by migrating from the CloudFormation specification to CloudFormation registry resource provider schemas and rewriting over 100 rules. This improves accuracy but may cause templates that previously passed to now fail, or require adjustments to custom rules/configurations.
Fix: Review templates against the new v1 rules and schemas. Update custom rules (if any) to align with the new `CloudFormationLintRule` base class and validation mechanisms. Refer to the official blog post for migration guidance.
gotcha cfn-lint frequently updates its internal CloudFormation schemas to reflect the latest AWS service features and property definitions. While beneficial for up-to-date validation, this can lead to templates that previously passed linting beginning to fail after a `cfn-lint` upgrade, even if the template itself hasn't changed.
Fix: Regularly review `cfn-lint` release notes for schema updates and new rules. Consider pinning `cfn-lint` versions in CI/CD pipelines and explicitly updating schemas with `--update-specs` in a controlled manner if you rely on the latest definitions.
gotcha The `cfn-lint` tool is often used as a command-line interface. There was also an older, deprecated `cfn-lint` npm package (JavaScript-based). Ensure you are installing and using the Python `cfn-lint` for the comprehensive features and active development.
Fix: Always use `pip install cfn-lint` for the Python version. If you encounter unexpected behavior or outdated rule sets, verify you are not using the npm package or an outdated Python installation.

Install

pip install cfn-lint Core installation
pip install "cfn-lint[full]" All optional features (graph, junit, sarif)
pip install "cfn-lint[graph]" With graph generation support

Imports

CloudFormationLintRule
```
from cfnlint.rules import CloudFormationLintRule
```
Primarily for developing custom linting rules to extend cfn-lint's capabilities. The main linting execution is via the `cfn-lint` command-line interface.

Quickstart

This quickstart demonstrates how to programmatically invoke the `cfn-lint` CLI tool from Python to validate a CloudFormation template. It creates a simple YAML template with a known issue (`InvalidProperty` on an S3 bucket), runs `cfn-lint` against it, captures the output, and then cleans up the temporary file.

import subprocess
import os

# Create a dummy CloudFormation template file with an intentional error
template_content = """
AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyS3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: my-unique-bucket-name
      # Intentional error: 'InvalidProperty' is not a valid S3 Bucket property
      InvalidProperty: true
"""

template_file = "./my_bad_template.yaml"
with open(template_file, "w") as f:
    f.write(template_content)

print(f"Linting {template_file} with cfn-lint...")

try:
    # Run cfn-lint as a subprocess
    # --format text is default, but explicit for clarity
    # --non-zero-exit-code error ensures a non-zero exit if errors are found
    result = subprocess.run(
        ['cfn-lint', template_file, '--non-zero-exit-code', 'error'],
        capture_output=True, text=True, check=False
    )

    print("\n--- cfn-lint Output ---")
    print(result.stdout)
    if result.stderr:
        print("\n--- cfn-lint Errors ---")
        print(result.stderr)

    if result.returncode != 0:
        print(f"\ncfn-lint found issues! Exit Code: {result.returncode}")
    else:
        print("\ncfn-lint found no issues.")

except FileNotFoundError:
    print("Error: cfn-lint command not found. Please ensure it's installed and in your PATH.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    # Clean up the dummy template file
    if os.path.exists(template_file):
        os.remove(template_file)
        print(f"\nCleaned up {template_file}")

view raw JSON →