Ansible Pilot

Ansible troubleshooting - Error 305: command-instead-of-shell

How to Solve the Ansible Error 305 command-instead-of-shell

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


Ansible, the popular automation tool, provides a powerful platform for managing and configuring IT infrastructure efficiently. While Ansible offers various modules to execute tasks, it’s crucial to choose the right module for specific use cases. Ansible-Lint, a widely-used linting tool for Ansible playbooks, enforces rules to help you follow best practices. In this article, we’ll delve into Rule 305, “command-instead-of-shell,” which encourages the use of the command module over the shell module when it’s not necessary to employ shell features.

Understanding Rule 305

Rule 305, “command-instead-of-shell,” is a valuable guideline that promotes efficiency and best practices in Ansible playbooks. It suggests that the command module should be preferred over the shell module unless specific shell features, such as environment variable expansion or chaining multiple commands using pipes, are required.

Problematic Code

Let’s explore a piece of problematic code that Rule 305 can identify in your playbooks:

- name: Problematic example
  hosts: all
    - name: Echo a message echo hello # <-- command is better in this case
      changed_when: false

In this code snippet, the playbook utilizes the shell module ( to execute a simple command that echoes a message. While this code will work, it’s not the most efficient or recommended approach.


WARNING  Listing 1 violation(s) that are fatal
command-instead-of-shell: Use shell only when shell functionality is required.
305.yml:5 Task/Handler: Echo a message

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

                   Rule Violation Summary                    
 count tag                      profile rule associated tags 
     1 command-instead-of-shell basic   command-shell, idiom 

Failed: 1 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

The corrected code that adheres to Rule 305 is as follows:

- name: Correct example
  hosts: all
    - name: Echo a message
      ansible.builtin.command: echo hello
      changed_when: false

In this improved version, the command module (ansible.builtin.command) is used to execute the same “echo” command. This approach aligns with best practices and is more efficient.

Why Choose the Command Module Over the Shell Module

The command module is preferred over the shell module in many cases due to several advantages:

  1. Efficiency: The command module is considerably faster than the shell module, making your playbooks run more quickly.

  2. Predictability: Using the command module ensures more predictable and reliable execution, as it doesn’t involve shell-specific behavior.

  3. Idempotence: The command module is idempotent by design, meaning it only makes changes when necessary, enhancing playbook reliability.

  4. Security: By avoiding unnecessary shell access, you reduce potential security risks and vulnerabilities.

Exception Handling

While Rule 305 encourages the use of the command module, there may be situations where you genuinely need the features offered by the shell module. In such cases, it’s essential to carefully consider whether the use of shell features justifies the performance trade-off. If you find that the shell module is indeed necessary, you can continue using it with an understanding of the potential efficiency implications.


Rule 305, “command-instead-of-shell,” is a valuable guideline within Ansible-Lint that promotes efficiency and best practices in Ansible playbooks. By choosing the command module over the shell module when shell-specific features are not required, you can enhance the speed, predictability, and reliability of your automation tasks. This practice contributes to a more efficient and secure Ansible workflow, ultimately ensuring that your playbooks perform optimally and effectively manage your IT infrastructure.

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