Install & Compatibility
Where this runs
tested against v26.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.602s · 70.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.9s · import 0.528s · 76MB
77MB installed
● package 77MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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()
ansible-lint --version
Debug
Known issues
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.fixUpgrade your Python environment to 3.10+ or pin `ansible-lint<23.0.0`.
affects: >=23.0.0
breakingMajor `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.fixReview 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.
affects: >=6.0.0
gotchaThe 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.fixAlways review the configuration documentation for your specific `ansible-lint` version when upgrading. Regenerate or carefully adapt existing configuration files.
affects: All major versions
gotchaWhile `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.fixPin `ansible-lint` to a specific version for programmatic integrations and perform thorough regression testing when upgrading to a new major or minor version.
affects: All versions
Errors
Common errors & fixes
Couldn't parse task at playbook.yml:6 (conflicting action statements: debug, __line__
This error occurs when a task in the playbook has conflicting action statements, leading to parsing issues.
fixEnsure that each task in your playbook has a single, clear action statement without conflicts.
syntax-check[unknown-module]: couldn't resolve module/action
This error indicates that Ansible-lint cannot resolve a module or action, possibly due to missing or uninstalled collections or roles.
fixEnsure all required collections and roles are listed in a 'requirements.yml' file and installed properly.
internal-error: An internal error occurred while processing the file
This error can be caused by internal bugs or issues within custom rules, leading to processing failures.
fixReview the detailed error message provided, check for issues in custom rules, and consider adding the 'internal-error' rule to the 'warn_list' until resolved.
ignore-errors: Tasks should not use 'ignore_errors' directive
Using 'ignore_errors: true' in tasks can hide actual failures and lead to unexpected behavior.
fixInstead of 'ignore_errors', use 'register' to capture errors and 'failed_when' to specify acceptable error conditions.
avoid-implicit[copy-content]: 'content' should be a string
The 'content' parameter in the 'copy' module is not a string, which can lead to unexpected behavior.
fixUse explicit Jinja templating to convert the content to a string, e.g., 'content: "{{ content | to_json }}"'. Upgrade
Version history
26.8.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
No dependency data recorded yet.