Registry / aws / cfn-lint

cfn-lint

JSON →
library1.55.1pypypi✓ verified 26d ago

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.

pip install cfn-lint
INSTALL
IMPORT
SIG · CFN-LINT
C
cfn-lint
awspythonv1.55.1
Install
11.0s avg
Import
2979ms
Disk
170MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.55.1 · 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.103.915 runs
installs and imports cleanly · install 0.0s · import 3.065s · 138.9MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 11.0s · import 2.893s · 141MB
170MB installed
● package 170MB
Code
Verified usage

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

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.

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}")
cfn-lint --version
Debug
Known issues
breakingPython 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`)
affects: >=1.47.0
breakingcfn-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.
affects: >=1.0.0
gotchacfn-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.
affects: All versions
gotchaThe `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.
affects: All versions
Errors
Common errors & fixes
E3002 Invalid Property Resources/<Resource-Name>/Properties/<PropertyName>
This error indicates that a property specified for a CloudFormation resource is either misspelled, does not exist, or is not supported for that specific resource type according to the AWS CloudFormation resource specification.
fix
Review the CloudFormation template and correct the property name or remove the unsupported property, ensuring it adheres to the official AWS CloudFormation documentation for the specified resource type.
E3003 Property <PropertyName> missing at Resources/<Resource-Name>
This error signifies that a required property for a particular CloudFormation resource is not present in the template.
fix
Add the missing required property to the resource definition in your CloudFormation template, referring to the AWS CloudFormation resource specification for the correct syntax and value.
W3002 This code may only work with package cli command as the property (/TemplateURL) is a string
This warning commonly occurs in nested CloudFormation stacks when `TemplateURL` references a local file path instead of an S3 URL, meaning the template needs to be packaged before deployment.
fix
Either upload the nested stack template to an S3 bucket and provide its S3 URL, or use the `aws cloudformation package` command to prepare the template for deployment, which will upload local artifacts to S3 and update the `TemplateURL` automatically.
E0002 Unknown exception while processing rule E<rule-id>: <exception-details>
This error indicates an unexpected internal exception within `cfn-lint` while processing a specific rule, often due to malformed intrinsic functions, incorrect data types in the template, or an incompatibility with `cfn-lint`'s parsing logic.
fix
Examine the CloudFormation template at the indicated location for syntax errors, incorrect intrinsic function usage, or unexpected data types. Ensure your `cfn-lint` and its dependencies (like `pyrsistent` or `samtranslator`) are up to date, as this can sometimes resolve internal parsing issues.
E3001 Invalid or unsupported Type <ResourceType> for resource <ResourceName> in <region>
This error means that the specified CloudFormation resource type is either invalid, misspelled, or not supported in the AWS region where the linting is being performed.
fix
Verify the resource type's spelling and ensure it is a valid CloudFormation resource type. Confirm that the resource type is available in the specified AWS region, and adjust the resource type or the target region if necessary.
Upgrade
Version history
1.55.1latest on PyPI · released Aug 13, 2026
Audit
Dependencies
aws-sam-translatorrequiredRequired for SAM template validation.
jsonpatchrequiredUsed for JSON patch operations, likely related to schema modifications.
networkxrequiredFor graph-related functionalities if optional 'graph' is installed.
pyyamlrequiredFor parsing YAML CloudFormation templates.
regexrequiredFor advanced regular expression matching in rules.
sympyrequiredUsed for symbolic mathematics, potentially in complex rule evaluations.
typing_extensionsrequiredProvides backports of Python 3.8+ typing features for broader compatibility.
pydotoptionalOptional dependency for generating resource dependency graphs.
junit-xmloptionalOptional dependency for JUnit output format.
sarif-omoptionalOptional dependency for SARIF output format.
Agent activity
16 hits · last 30 days
node
12
Resources
cfn-lint — pip install cfn-lint · libregistry