{"id":2383,"library":"ansible-lint","title":"Ansible Lint","description":"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.","status":"active","version":"26.4.0","language":"en","source_language":"en","source_url":"https://github.com/ansible/ansible-lint","tags":["ansible","linter","static analysis","devops","automation"],"install":[{"cmd":"pip install ansible-lint","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Main application object for programmatic linting.","symbol":"App","correct":"from ansiblelint.app import App"},{"note":"Configuration object used to pass options to the App.","symbol":"Options","correct":"from ansiblelint.config import Options"},{"note":"Object representing a single linting issue or match.","symbol":"MatchError","correct":"from ansiblelint.errors import MatchError"}],"quickstart":{"code":"import os\nimport tempfile\nfrom pathlib import Path\nfrom ansiblelint.app import App\nfrom ansiblelint.config import Options\n\n# Create a temporary playbook file for linting\nplaybook_content = \"\"\"\n---\n- name: Example playbook with common linting issues\n  hosts: localhost\n  tasks:\n    - name: Using command module directly (LINT: no-shell-command)\n      ansible.builtin.command: echo \"hello world\"\n    - name: Insecure default permissions for file (LINT: risky-file-permissions)\n      ansible.builtin.file:\n        path: /tmp/testfile.txt\n        state: touch\n        mode: \"0777\" # Risky permissions\n\"\"\"\n\ntemp_dir = Path(tempfile.mkdtemp())\nplaybook_path = temp_dir / \"playbook.yml\"\nwith open(playbook_path, \"w\") as f:\n    f.write(playbook_content)\n\ntry:\n    # Configure linting options\n    options = Options()\n    # Prevent App from configuring logging globally, for cleaner output in example\n    options.configure_logger = False\n    # Specify the file(s) to lint\n    options.lintables = [str(playbook_path)]\n    # Set up app and run lint\n    app = App(options)\n    matches = app.run()\n\n    print(f\"Linting results for {playbook_path.name}:\")\n    if matches:\n        for match in matches:\n            print(f\"- [{match.rule_id}] {match.message} (File: {match.filename}, Line: {match.linenumber})\")\n    else:\n        print(\"No linting issues found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the temporary directory and file\n    if temp_dir.exists():\n        for item in temp_dir.iterdir():\n            item.unlink()\n        temp_dir.rmdir()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10+ or pin `ansible-lint<23.0.0`.","message":"`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.","severity":"breaking","affected_versions":">=23.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Always review the configuration documentation for your specific `ansible-lint` version when upgrading. Regenerate or carefully adapt existing configuration files.","message":"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.","severity":"gotcha","affected_versions":"All major versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}