Ansible Lint: Check & Fix Playbooks for Best Practices (2026 Guide)

Introduction

If you’re involved in managing infrastructure, you probably already know the power and flexibility of Ansible, an open-source configuration management tool. Ansible allows you to automate the configuration of one or many machines, ensuring that tasks are performed consistently, whether you’re provisioning virtual machines, installing applications, or applying updates. But how can you be sure your Ansible playbooks are free from errors and follow best practices? That’s where linting comes into play.

What is Ansible?

Ansible is a widely-used configuration management software that simplifies automation tasks for IT professionals and system administrators. With Ansible, you can define tasks in YAML files called playbooks. These tasks can include setting up servers, installing software, creating users, and much more. The real power of Ansible lies in its ability to perform these tasks consistently across multiple machines, making it a crucial tool in the world of infrastructure management.

Why Lint Ansible?

Ansible playbooks are written in YAML, a human-readable data serialization format. While YAML is user-friendly, it is strict about syntax, indentation, and formatting. Linting helps you ensure that your Ansible playbooks adhere to these YAML standards, making your code more readable and less prone to errors.

Linting also checks for issues beyond just syntax. It enforces best practices, catches deprecated features, and identifies potential security vulnerabilities. Linting is a proactive step that can save you time and headaches by preventing issues before they occur.

See also: Exploring Ansible-Lint Profiles: A Comprehensive Guide

Installation

To begin linting your Ansible playbooks, you’ll need to install ansible-lint, a tool specifically designed for this purpose. Ensure you have Ansible installed first, and then use the following commands to install ansible-lint:

pip3 install ansible-lint
ansible-lint --version

Example output

ansible-lint 6.21.1 using ansible-core:2.15.5 ansible-compat:4.1.10 ruamel-yaml:0.17.39 ruamel-yaml-clib:0.2.8

Manual Linting

Once ansible-lint is installed, you can manually lint your Ansible playbooks and roles. Start by listing the available linting rules with:

ansible-lint -L

This will provide you with a list of rules that ansible-lint will use to analyze your code. The rules cover a wide range of issues, from basic syntax errors to best practices.

To lint a specific playbook or role, use the following command:

ansible-lint playbook.yml

When linting, ansible-lint will display messages in the following format for each issue it detects: The rule that triggered the issue. The file that contains the error and the line number. The offending line of code.

For instance, if ansible-lint finds an issue with a playbook, it will display the rule, file, and line number, making it easier to identify and correct the problem.

See also: Ansible-Lint: Complete Guide to Linting Playbooks & Roles

Linting Example

Let’s take a real-world example of linting in Ansible. Consider a playbook that installs packages using the pip module:

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Install pip packages
      ansible.builtin.pip:
        name:
          - ansible-lint
        state: latest

In this code, the issue is the use of the state: latest tag when installing packages. This could lead to inconsistencies between machines as the latest version might differ from one run to another. ansible-lint identifies this issue and provides the following feedback:

[403] Package installs should not use latest playbook.yml:9 Task/Handler: Install pip packages

The recommended solution is to specify a version number for each package, ensuring consistency across deployments:

---
- name: Example playbook
  hosts: all
  tasks:
    - name: Install pip packages
      ansible.builtin.pip:
        name:
          - ansible-lint>=6.0
        state: present

Linting vs Syntax-Checking

It’s important to distinguish between linting and syntax-checking in Ansible. Syntax-checking ensures that your code adheres to YAML formatting rules and is free of basic syntax errors. You can perform syntax-checking using Ansible’s built-in tool with the following command:

ansible-playbook --syntax-check playbook.yml

Linting, as discussed in this article, goes a step further. It not only checks syntax but also enforces best practices, code consistency, and identifies potential issues that may not be apparent during syntax-checking.

See also: Enhancing Ansible Role Development with Best Practices with ansible-later

Conclusion

Linting Ansible playbooks are crucial in maintaining code quality, consistency, and reliability in your infrastructure automation projects. ansible-lint provides a powerful set of rules and guidelines to help you catch errors, enforce best practices, and ensure your playbooks are written consistently and maintainably.

Related Articles

• role dependencies in Ansible • listen-based handlers in Ansible