Ansible Lint

26.4.0 · active · verified Fri Apr 10

Ansible Lint is a command-line tool that checks Ansible playbooks, roles, and collections for practices and behavior that could potentially be improved. It helps maintain code quality, enforce best practices, and identify common pitfalls in Ansible automation. The current version is 26.4.0, and it maintains an active release cadence, often with multiple updates per month to incorporate new rules and keep pace with Ansible Core development.

Warnings

breaking `ansible-lint` versions `23.x` and newer require Python `3.10` or later. Users on older Python versions (e.g., 3.8, 3.9) will encounter installation or runtime errors and must upgrade their Python environment or use an older `ansible-lint` version.
Fix: Upgrade your Python environment to 3.10+ or pin `ansible-lint<23.0.0`.
breaking Major `ansible-lint` releases (e.g., 6.x, 23.x) frequently introduce new rule IDs, rename existing ones, and modify the set of rules enabled by default. This can cause previously passing playbooks to fail lint checks or require updates to custom `.ansible-lint` configurations to suppress/enable specific rules.
Fix: Review the release notes for rule changes when upgrading. Update your `.ansible-lint` configuration to adjust enabled/disabled rules as needed, or explicitly specify `--strict-annotations` to enforce comments.
gotcha The schema and available options within the `.ansible-lint` configuration file are subject to change between versions. Using a configuration file from an older `ansible-lint` version with a newer installation can lead to ignored settings, warnings about unknown options, or unexpected linting behavior.
Fix: Always review the configuration documentation for your specific `ansible-lint` version when upgrading. Regenerate or carefully adapt existing configuration files.
gotcha While `ansible-lint` offers a Python API (e.g., `ansiblelint.app.App`, `ansiblelint.runner.Runner`), its public interface is not as strictly stable as its CLI. Direct programmatic usage should be thoroughly tested after each `ansible-lint` upgrade, as internal changes might affect custom integrations.
Fix: Pin `ansible-lint` to a specific version for programmatic integrations and perform thorough regression testing when upgrading to a new major or minor version.

Install

pip install ansible-lint Install stable version

Imports

App
```
from ansiblelint.app import App
```
Main application object for programmatic linting.
Options
```
from ansiblelint.config import Options
```
Configuration object used to pass options to the App.
MatchError
```
from ansiblelint.errors import MatchError
```
Object representing a single linting issue or match.

Quickstart

This quickstart demonstrates how to programmatically use `ansible-lint` to check a playbook. It creates a temporary Ansible playbook file with known linting issues, initializes the `App` with specific options, runs the linting process, and prints any identified issues. The example also includes cleanup of the temporary files.

import os
import tempfile
from pathlib import Path
from ansiblelint.app import App
from ansiblelint.config import Options

# Create a temporary playbook file for linting
playbook_content = """
---
- name: Example playbook with common linting issues
  hosts: localhost
  tasks:
    - name: Using command module directly (LINT: no-shell-command)
      ansible.builtin.command: echo "hello world"
    - name: Insecure default permissions for file (LINT: risky-file-permissions)
      ansible.builtin.file:
        path: /tmp/testfile.txt
        state: touch
        mode: "0777" # Risky permissions
"""

temp_dir = Path(tempfile.mkdtemp())
playbook_path = temp_dir / "playbook.yml"
with open(playbook_path, "w") as f:
    f.write(playbook_content)

try:
    # Configure linting options
    options = Options()
    # Prevent App from configuring logging globally, for cleaner output in example
    options.configure_logger = False
    # Specify the file(s) to lint
    options.lintables = [str(playbook_path)]
    # Set up app and run lint
    app = App(options)
    matches = app.run()

    print(f"Linting results for {playbook_path.name}:")
    if matches:
        for match in matches:
            print(f"- [{match.rule_id}] {match.message} (File: {match.filename}, Line: {match.linenumber})")
    else:
        print("No linting issues found.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the temporary directory and file
    if temp_dir.exists():
        for item in temp_dir.iterdir():
            item.unlink()
        temp_dir.rmdir()

view raw JSON →