Check Mode and Diff Mode

ansible-playbook --check runs a play without changing anything — every module reports what it would do against the live machine, and --diff shows the exact before/after of any file it would touch. This is the closest thing Ansible has to a plan.

Since there is no state file to read, the dry run works by having each module inspect the real node and predict its change, so --check --diff is your pre-flight against the actual server, not against a recorded snapshot. It is the no-state-file equivalent of the planning step a provisioning tool runs before it applies.

--check as a Dry Run

Under --check, every module runs in predict-only mode: it reports changed or ok as if it had acted, but writes nothing. Running the Larkspur web play under --check tells you whether a real run would restart gunicorn or rewrite larkspur.conf before you let it touch anything.

The prediction comes from the same machinery the last topics described. Each module reads the live host and compares to the declared state — exactly what it does on a real run — and stops short of writing. The changed/ok it reports is the honest one, just without the side effect.

--diff for File Changes

Paired with --check, --diff prints a unified diff of what template, copy, or lineinfile would change in app.env or the nginx config. You read the literal lines that would change, which is the review a config push deserves.

A bare changed count tells you that a file would change; the diff tells you what. Those are different facts, and the second one is what actually lets you approve the push — you are signing off on specific lines, not on a number.

The Dry Run That Substitutes for plan

A provisioning tool reads its state file to compute a plan; Ansible has no state, so --check computes "what would change" by having each module query the live host directly. The prediction is against reality on the spot, which is why it can catch a hand-edited drift a stored plan would miss.

This is the spine of the course showing up as a feature. No state file means the dry run cannot be stale relative to the world, because it never consulted a recorded snapshot — it asked the machine. The trade-off, covered below, is that it predicts one task at a time.

Modules That Do Not Support Check Mode

command and shell cannot predict their effect — Ansible has no idea what an arbitrary command would do without running it — so under --check they skip by default and report nothing useful. A play built on raw commands therefore has a weak dry run.

This is one more reason to prefer real modules, beyond the idempotency argument from two topics back. A real module implements check mode honestly and shows you its prediction; a raw command leaves a blank where the most important file change might be.

The Limits of the Prediction

--check is per-task against current state, so a task whose outcome depends on an earlier task's change can mispredict — the earlier change did not actually happen in check mode, so the later task sees the unchanged host. A task that edits a file created by a previous task may report differently in check than in a real run.

The dry run is a strong sanity pass, not a guarantee that a real run is identical. Treat a clean --check as "no obvious surprises in single tasks," not as "this run is proven safe end to end," and keep that limit in mind for plays with inter-task dependencies.

Where It Fits

--check --diff is the gate before a production push: run it on the canary host, read the diff, confirm only the intended files and services change, then run for real. It is the habit that turns "I think this play is safe" into "I read exactly what it does."

Make it a reflex for any config push. The web play that rewrites app.env and might restart gunicorn is exactly the kind of change you want to see in diff form on one host before it reaches the fleet, and the cost of running it first is a few seconds.