AWS CloudFormation Linter

Validate AWS CloudFormation yaml/json templates against the AWS CloudFormation resource provider schemas and additional checks. Includes checking valid values for resource properties and best practices.

Warning

This is an attempt to provide validation for AWS CloudFormation templates properties and their values. For values things can get pretty complicated (mappings, joins, splits, conditions, and nesting those functions inside each other) so it's a best effort to validate those values but the promise is to not fail if we can't understand or translate all the things that could be going on.

Contribute

We encourage you to contribute to cfn-lint! Please check out the Contributing Guidelines for more information on how to proceed.

Community

Join us on Discord! Connect & interact with CloudFormation developers & experts, find channels to discuss and get help for cfn-lint, CloudFormation registry, StackSets, Guard and more:

Serverless Application Model

The Serverless Application Model (SAM) is supported by the linter. The template is transformed using AWS SAM before the linter processes the template.

To get information about the SAM Transformation, run the linter with --info

Install

Python 3.9 to 3.13 are supported.

Pip

pip install cfn-lint. If pip is not available, run python setup.py clean --all then python setup.py install.

Optional dependencies

cfn-lint has optional dependencies based on certain features you may need.

pip install cfn-lint[full] for installing all the optional dependencies. This will install all the dependencies for graph, junit, and sarif.
pip install cfn-lint[graph] for installing pydot to draw and output template graphs
pip install cfn-lint[junit] for installing the packages to output the junit format
pip install cfn-lint[sarif] for installing the packages to output the sarif format

Homebrew (macOS)

brew install cfn-lint

Docker

In cfn-lint source tree:

docker build --tag cfn-lint:latest .

In repository to be linted:

docker run --rm -v `pwd`:/data cfn-lint:latest /data/template.yaml

Editor Plugins

There are IDE plugins available to get direct linter feedback from you favorite editor:

Atom
Emacs
NeoVim 0.2.0+/Vim 8
- ALE
- Coc
- Syntastic
Sublime
Visual Studio Code
IntelliJ IDEA

GitHub Action

Online demo

Basic Usage

cfn-lint template.yaml
cfn-lint -t template.yaml

Multiple files can be linted by either specifying multiple specific files:

cfn-lint template1.yaml template2.yaml
cfn-lint -t template1.yaml template2.yaml

or by using wildcards (globbing):

Lint all yaml files in path:

cfn-lint path/*.yaml

Lint all yaml files in path and all subdirectories (recursive):

cfn-lint path/**/*.yaml

Note: If using sh/bash/zsh, you must enable globbing. (shopt -s globstar for sh/bash, setopt extended_glob for zsh).

Exit Codes

cfn-lint will return a non zero exit if there are any issues with your template. The value is dependent on the severity of the issues found. For each level of discovered error cfn-lint will use bitwise OR to determine the final exit code. This will result in these possibilities.

0 is no issue was found
2 is an error
4 is a warning
6 is an error and a warning
8 is an informational
10 is an error and informational
12 is an warning and informational
14 is an error and a warning and an informational

Configuring Exit Codes

cfn-lint allows you to configure exit codes. You can provide the parameter --non-zero-exit-code with a value of informational, warning, error, or none. cfn-lint will determine the exit code based on the match severity being the value of the parameter --non-zero-exit-code and higher. The exit codes will remain the same as above.

The order of severity is as follows:

informational default
warning
error
none Exit code will always be 0 unless there is a syntax error

Specifying the template as an input stream

The template to be linted can also be passed using standard input:

cat path/template.yaml | cfn-lint -

Specifying the template with other parameters

cfn-lint -r us-east-1 ap-south-1 -- template.yaml
cfn-lint -r us-east-1 ap-south-1 -t template.yaml

Configuration

Command Line

From a command prompt run cfn-lint <path to template> to run standard linting of the template.

Config File

It will look for a configuration file in the following locations (by order of preference):

.cfnlintrc, .cfnlintrc.yaml or .cfnlintrc.yml in the current working directory
~/.cfnlintrc for the home directory

In that file you can specify settings from the parameter section below.

Example:

templates:
  - test/fixtures/templates/good/**/*.yaml
ignore_templates:
  - codebuild.yaml
include_checks:
  - I
custom_rules: custom_rules.txt

Parameters

Optional parameters:

Command Line	Metadata	Options	Description
-h, --help			Get description of cfn-lint
-z, --custom-rules		filename	Text file containing user-defined custom rules. See here for more information
-t, --template		filename	Alternative way to specify Template file path to the file that needs to be tested by cfn-lint
--deployment-files	deployment_files		Specify deployment files that are used to configure the template runner. This will specify templates and parameters and you don't specify parameters or parameter files with this parameter. Examples of a deployment include: GitSync
--parameters	parameters		Specify a list of parameters using the format `Key=Value`
--parameter-files	parameter_files		A list of parameter files that would be used when using the aws cli
-f, --format	format	quiet, parseable, json, junit, pretty, sarif	Output format

cfn-lint

Description