Skip to main content

Command-line utility that validates jinja2 syntax according to Arista's AVD style guide.

Project description

GitHub license PyPI version PyPI pyversions PyPI status Maintenance


AVD Ecosystem - Jinja2 Linter

Project Goals

Build a Jinja2 linter that will provide the following capabilities:

  • Validate syntax according to AVD style guide.
  • Capability to run as part of a CI pipeline to enforce j2lint rules.
  • Develop an extension that works with VSCode and potentially other IDEs i.e PyCharm.

Syntax and code style issues

Code Short Description Description
S0 jinja-syntax-error Jinja2 syntax should be correct
S1 single-space-decorator A single space should be added between Jinja2 curly brackets and a variable's name
S2 operator-enclosed-by-spaces When variables are used in combination with an operator, the operator shall be enclosed by space
S3 jinja-statements-indentation Nested jinja code block should follow next rules:
- All J2 statements must be enclosed by 1 space
- All J2 statements must be indented by 4 more spaces within jinja delimiter
- To close a control, end tag must have same indentation level
S4 jinja-statements-single-space Jinja statement should have at least a single space after '{%' and a single space before '%}'
S5 jinja-statements-no-tabs Indentation should not use tabulation but 4 spaces
S6 jinja-statements-delimiter Jinja statements should not have {%- or {%+ or -%} as delimiters
S7 single-statement-per-line Jinja statements should be on separate lines
V1 jinja-variable-lower-case All variables should use lower case
V2 jinja-variable-format If variable is multi-words, underscore _ should be used as a separator

Getting Started


Python version 3.8+

Install with pip

To get started, you can use Python pip to install j2lint:

Install the latest stable version:

pip3 install j2lint

Install the latest development version:

pip3 install git+

Running the linter

j2lint <path-to-directory-of-templates>

Running the linter on a specific file

j2lint <path-to-directory-of-templates>/template.j2

Listing linting rules

j2lint --list

Running the linter with verbose linter error output

j2lint <path-to-directory-of-templates> --verbose

Running the linter with logs enabled. Logs saved in jinja2-linter.log in the current directory

j2lint <path-to-directory-of-templates> --log

To enable debug logs, use both options:

j2lint <path-to-directory-of-templates> --log --debug

Running the linter with JSON format for linter error output

j2lint <path-to-directory-of-templates> --json

Ignoring rules

  1. The --ignore option can have one or more of these values: syntax-error, single-space-decorator, filter-enclosed-by-spaces, jinja-statement-single-space, jinja-statements-indentation, no-tabs, single-statement-per-line, jinja-delimiter, jinja-variable-lower-case, jinja-variable-format.

  2. If multiple rules are to be ignored, use the --ignore option along with rule descriptions separated by space.

    j2lint <path-to-directory-of-templates> --ignore <rule_description1> <rule_desc>

Note This runs the custom linting rules in addition to the default linting rules. When using the -i/--ignore or -w/--warn options, the arguments MUST either:

  • Be entered at the end of the CLI as in the example above
  • Be entered as the last options before the <path-to-directory-of-templates> with -- separator. e.g.
    j2lint --ignore <rule_description1> <rule_desc> -- <path-to-directory-of-templates>
  1. If one or more linting rules are to be ignored only for a specific jinja template file, add a Jinja comment at the top of the file. The rule can be disabled using the short description of the rule or the id of the rule.

    {# j2lint: disable=S6}
    # OR
    {# j2lint: disable=jinja-delimiter #}
  2. Disabling multiple rules

    {# j2lint: disable=jinja-delimiter j2lint: disable=S1 #}

Adding custom rules

  1. Create a new rules directory under j2lint folder.

  2. Add custom rule classes which are similar to classes in j2lint/rules directory: The file name of rules should be in snake_case and the class name should be the PascalCase version of the file name. For example:

    • File name:
    • Class name: JinjaOperatorHasSpacesRule
  3. Run the jinja2 linter using --rules-dir option

    j2lint <path-to-directory-of-templates> --rules-dir <custom-rules-directory>

Note This runs the custom linting rules in addition to the default linting rules.

Running jinja2 linter help command

j2lint --help

Running jinja2 linter on STDIN template. This option can be used with VS Code.

j2lint --stdin

Using j2lint as a pre-commit-hook

  1. Add j2lint pre-commit hook inside your repository in .pre-commit-config.yaml.

    - repo:
        rev: <release_tag/sha>
        - id: j2lint
  2. Run pre-commit -> pre-commit run --all-files

Note When using -i/--ignore or -w/--warn argument in pre-commit, use the following syntax

- repo:
    rev: <release_tag/sha>
    - id: j2lint
    # Using -- to separate the end of ignore from the positional arguments
    # passed to j2lint
      args: [--ignore, S3, jinja-statements-single-space, --]


This project is based on salt-lint and jinjalint

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

j2lint-1.1.0.tar.gz (28.7 kB view hashes)

Uploaded Source

Built Distribution

j2lint-1.1.0-py3-none-any.whl (30.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page