Ansible Playbook Dry Run: Run Playbook in "Check Mode"

November 19, 2020


Ansible is an Infrastructure as Code tool that allows you to use a single control node to monitor and manage remote servers.

Ansible lets you manage remote servers by creating playbooks, which contain lists of tasks for the remote servers to perform. It also provides a check mode in which you can test a playbook.

This tutorial shows you how to do a dry run of an Ansible playbook by using the built-in check mode feature.

Anible Playbook Dry Run: Run Playbook in Check Mode.


When to Use Ansible Dry Run

Using Ansible’s dry run feature enables users to execute a playbook without making changes to the servers. It uses the built-in check mode to proof a playbook for errors before execution.

This option is very useful when executing complex playbooks that contain commands which make major changes to servers. Using the dry run feature helps find fatal errors before they shut down servers and make them unusable.

Ansible Dry Run – Executing Playbooks in Check Mode

The easiest way to do a dry run in Ansible is to use the check mode. This mode works like the --syntax-check command, but on a playbook level.

Check Mode

Use the -C or --check flag with the ansible-playbook command to do a dry run of an Ansible playbook:

ansible-playbook playbook.yaml --check

This produces the same output as actually running the playbook, except it will report on changes it would have made rather than making them.

Ansible playbook dry run using the check mode

Another way to run a playbook in check mode is to add the check_mode parameter to the playbook content:

- hosts: all
  - name: A command to run in check mode
    command: /your/command
    check_mode: on

Diff Option

Using the --diff flag with the ansible-playbook command reports what changes were made while executing the playbook:

ansible-playbook playbook.yaml --diff

Using the --diff flag produces a lengthy output, so it’s best used when checking for changes on a single host.

Running an Ansible playbook using diff mode

Combining Check and Diff

Combining the --check and --diff flags with the ansible-playbook command gives you a more detailed overview of all the changes made by your playbook:

ansible-playbook playbook.yaml --check --diff

This produces the same detailed output you get when using the --diff flag, but without actually executing any of the changes.

Using check and dif mode together on an Ansible playbook

When Not to Use Ansible Dry Run

Using the dry run feature is useful for node-by-node basic configuration management.

However, if your playbook contains conditional or result-based tasks, it won’t work in check mode. This is because the conditions for those tasks can’t be satisfied without actually executing the playbook and making changes.


After following this tutorial, you should know how to use the --check and --diff flags to perform a dry run of an Ansible playbook.

You should also be able to recognize when and when not to perform dry runs.

Was this article helpful?
Sofija Simic
Sofija Simic is an experienced Technical Writer. Alongside her educational background in teaching and writing, she has had a lifelong passion for information technology. She is committed to unscrambling confusing IT concepts and streamlining intricate software installations.
Next you should read
phoenixNAP Bare Metal Cloud Billing Models
October 30, 2020

This article talks about the available billing models for Bare Metal Cloud servers. Here, you will also learn…
Read more
How to Install and Configure Ansible on Windows
May 30, 2024

Ansible is a Linux-based app used for monitoring and managing remote severs. There are several ways you can…
Read more
How to Install phoenixNAP BMC Ansible Module
July 24, 2020

Learn how to successfully install the Bare Metal Cloud Ansible module on your control machine. Take a look at…
Read more
What is Bare Metal Cloud
May 20, 2020

This article provides answers to everything you wanted to know about Bare Metal Cloud and how it compares to…
Read more