Ansible Pilot

Ansible troubleshooting - Error 303: command-instead-of-module

How to Solve the Ansible Error 303 command-instead-of-module Enhancing Ansible Playbooks

October 31, 2023
Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons


In the world of Ansible automation, best practices and efficiency are paramount. Ansible-Lint, a popular linting tool for Ansible playbooks, comes with a variety of rules to help you follow best practices, maintain consistency, and avoid common pitfalls. One such rule, Rule 303, “command-instead-of-module”, recommends using specific Ansible modules in place of commands for tasks where modules are a more reliable and feature-rich choice.

Understanding Rule 303

Rule 303, “command-instead-of-module”, serves as a friendly reminder that, in many cases, using Ansible modules is a better approach than running raw shell commands. Modules provide various benefits, including improved reliability, better messaging, and additional features like retry capabilities. By adhering to this rule, you can enhance the quality and maintainability of your Ansible playbooks.

Problematic Code

Let’s examine a common issue that Rule 303 can help identify in your playbooks:

- name: Update apt cache
  hosts: all
    - name: Run apt-get update
      ansible.builtin.command: apt-get update # <-- better to use ansible.builtin.apt module

In this code snippet, a raw command (apt-get update) is used to update the apt cache. While this approach may work, it’s not the most efficient or reliable way to achieve the task.


WARNING  Listing 2 violation(s) that are fatal
command-instead-of-module: apt-get used in place of apt-get module
303.yml:5 Task/Handler: Run apt-get update

no-changed-when: Commands should not change things if nothing needs doing.
303.yml:5 Task/Handler: Run apt-get update

Read documentation for instructions on how to ignore specific rule violations.

                       Rule Violation Summary                       
 count tag                       profile rule associated tags       
     1 command-instead-of-module basic   command-shell, idiom       
     1 no-changed-when           shared  command-shell, idempotency 

Failed: 2 failure(s), 0 warning(s) on 1 files. Last profile that met the validation criteria was 'min'.

The Best Resources For Ansible


Video Course

Printed Book


Correct Code

Here’s the corrected code that aligns with Rule 303:

- name: Update apt cache
  hosts: all
    - name: Run apt-get update
        update_cache: true

In the improved version, the “ansible.builtin.apt” module is utilized to update the apt cache. This module is purpose-built for managing packages and repositories, making the playbook more predictable and easier to maintain.

Why Use Modules Over Commands

Using modules over commands is an essential best practice in Ansible automation for several reasons:

  1. Reliability: Modules are designed to be idempotent, meaning they only make changes when necessary. This ensures that your playbooks will consistently produce the desired state.

  2. Readability: Modules often have better error messages and are more self-explanatory, improving the overall readability of your playbooks.

  3. Extensibility: Modules typically offer additional features and parameters that provide greater control and flexibility in your automation tasks.

  4. Cross-Platform Compatibility: Modules are cross-platform and work on various operating systems, making your playbooks more versatile.

  5. Security: Modules can handle sensitive data securely, reducing the risk of exposing sensitive information in your playbooks.

By following Rule 303 and embracing modules over commands, you can harness these advantages to create more efficient, reliable, and maintainable Ansible playbooks.

Exception Handling

In some rare cases, you may find that Rule 303 triggers false positives, recommending modules for tasks where commands are the appropriate choice. If this occurs, you can disable the rule for specific lines in your playbook by adding a comment like # noqa: command-instead-of-module to the same line. This exception handling allows you to maintain flexibility in your playbooks when needed.


Rule 303, “command-instead-of-module”, is a valuable guideline provided by Ansible-Lint to encourage best practices in Ansible automation. By prioritizing the use of Ansible modules over raw commands, you can enhance the reliability, readability, and security of your playbooks. Additionally, module usage ensures that your automation remains efficient and adaptable across various platforms, making it an essential practice for Ansible developers and operators.

Subscribe to the YouTube channel, Medium, and Website, X (formerly Twitter) to not miss the next episode of the Ansible Pilot.


Learn the Ansible automation technology with some real-life examples in my

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

BUY the Complete PDF BOOK to easily Copy and Paste the 250+ Ansible code

Want to keep this project going? Please donate

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons
Follow me

Subscribe not to miss any new releases