ansible-lint

Lint a specific playbook and a role directory

$ ansible-lint [path/to/playbook_file] [path/to/role_directory]

$ ansible-lint [[-x|--exclude-rules]] [rule1,rule2,...] [path/to/playbook_file]

$ ansible-lint [[-o|--offline]] [[-p|--parseable]] [path/to/playbook_file]

$ ansible-lint [[-r|--rules]] [path/to/custom_rules_directory] [path/to/playbook_file]

$ ansible-lint [path/to/project_directory]

ansible-lint [options] [playbook.yml | role/ | collection/ ...]

-h, --help
    Show help message and exit

-v, --verbose
    Increase verbosity (repeatable up to 4 times)

-q, --quiet
    Suppress warnings and non-fatal errors

--version
    Display ansible-lint version

--list-rules
    List all available rules with descriptions

-p PARALLEL, --parallel=PARALLEL
    Number of parallel jobs (default: 0, serial)

--parseable
    Compact format: filename:linenumber: message

--json
    JSON output format

--sarif
    SARIF output for static analysis tools

-x RULE, --exclude=RULE
    Skip rules matching comma-separated list

-w RULE, --warn=RULE
    Downgrade rules to warnings

--profile=PROFILE
    Use rule profile (e.g., 'production', 'normal')

--offline
    Skip role downloads and Galaxy lookups

--playbook-dir=DIR
    Directory to load playbooks from

--exclude-paths=PATHS
    Comma-separated paths or globs to exclude

ansible-lint is a command-line tool designed to ensure Ansible playbooks, roles, tasks, and collections adhere to best practices and identify potential issues before execution.

It performs static analysis on YAML files, checking for syntax errors, deprecated features, security risks, performance problems, and style violations. Rules are customizable and cover aspects like proper use of modules, variable definitions, task idempotency, and Jinja2 templating.

Ideal for CI/CD pipelines, it supports multiple formats (standard, parseable, JSON, SARIF) and integrates with editors via plugins. ansible-lint uses Ansible's parser for accuracy and supports progressive rule enforcement via profiles (normal, production).

Running it catches errors early, promotes consistency across teams, and improves playbook maintainability without executing code.

Requires Python 3.8+; some rules need Ansible core installed for full parsing. May produce false positives on custom modules. Not a syntax validator alone—use with ansible-playbook --syntax-check.

Supports .ansible-lint, ansible-lint.yml, or .ansible-lint/config.yml for custom rules, skips, profiles.
Example:
skip_list:
  - 'name[casing]'

0: OK
2: Linting errors found
1: Fatal error (syntax, usage)

Created by Will Thames in 2015 as ansible-lint for Ansible 1.x. Evolved with Ansible 2.x, split from ansible-core in 2021 (v22.0+). Now at v24+, maintained by Ansible community on GitHub with 100+ rules and semantic versioning.

ansible-playbook(1), ansible-galaxy(1), yamllint(1), shellcheck(1)