--limit and limit files · Ansible

--limit is the most-used safety control in Ansible, and it is misunderstood in one specific way that matters.

--limit intersects with the play’s hosts: line. It does not replace it.

The effective host list is the intersection of the two. A --limit can only ever make a play target fewer hosts than its hosts: line already selects — never more, never different.

That is a strong guarantee and it is the reason --limit is the right habitual way to narrow a run. It is also why a --limit naming a host the play never targeted quietly does nothing.

The intersection, demonstrated

Every example uses one playbook whose single play is hosts: web, against the ten-host inventory from lesson 2.

Read-only / Safeno limit - the play's own pattern— Real output from ansible-core 2.21.3. Four hosts, from the play's hosts: web.

$ ansible-playbook -i inventory/hosts.yml site.yml --list-hosts

playbook: site.yml

play #1 (web): Configure the web tier	TAGS: []
  pattern: ['web']
  hosts (4):
    web01.example.com
    web02.example.com
    web03.example.com
    web04.example.com

Read-only / Safe--limit narrows to one host— Real output from ansible-core 2.21.3. Note the pattern line still reads ['web'] - the play's own target is unchanged, and the host list below it is the intersection.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit web01.example.com --list-hosts

  play #1 (web): Configure the web tier	TAGS: []
  pattern: ['web']
  hosts (1):
    web01.example.com

Read-only / Safe--limit all does not widen anything— Real output from ansible-core 2.21.3. The inventory has ten hosts. The play still targets four, because --limit all intersects with web rather than replacing it.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit all --list-hosts

  play #1 (web): Configure the web tier	TAGS: []
  pattern: ['web']
  hosts (4):
    web04.example.com
    web02.example.com
    web03.example.com
    web01.example.com

That third case is the guarantee in action. There is no --limit value that reaches a host the play was not already going to reach.

The four shapes you will actually use

Configuration changesingle host - the smallest possible change— One host. The first form to reach for when validating anything on real infrastructure.

ansible-playbook -i inventory/ site.yml --limit web01.example.com --check --diff

Configuration changecanary group - a named set that survives inventory changes— Better than naming a host, because the canary group is a deliberate inventory decision rather than a hostname somebody memorised.

ansible-playbook -i inventory/ site.yml --limit canary

Configuration changeregion or environment - a blast-radius boundary that already exists— Intersects with the play's own pattern, so this is the web tier in one region without needing a combined group.

ansible-playbook -i inventory/ site.yml --limit eu_west

Configuration changea wave - the remainder after the canary— Operators work inside --limit exactly as they do in a play pattern, including exclusion.

ansible-playbook -i inventory/ site.yml --limit 'us_east:!canary'

-l is the short form and works identically on ansible, ansible-playbook and ansible-inventory:

Read-only / Safethe same limit on three commands— Real output from ansible-core 2.21.3, abbreviated. ansible-inventory --list honours --limit; --graph does not, which is the subject of the next lesson.

$ ansible -i inventory/hosts.yml web -l canary --list-hosts

  hosts (1):
  web01.example.com

Limit files

--limit @file reads the pattern from a file. This is the form that turns a host list into a reviewable artefact.

Read-only / Safechange-ops-5512.limit— Comments and blank lines are permitted. Group names and operators work exactly as in an inline pattern.

# change ticket OPS-5512 - approved 2026-08-11 by the platform team
# generated from: ansible -i inventory/ 'web:&eu_west' --list-hosts
web01.example.com

web03.example.com

Read-only / Safethe file drives the run— Real output from ansible-core 2.21.3. The comment and the blank line are ignored; two hosts result, still intersected with the play's hosts: web.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit @change-ops-5512.limit --list-hosts

  play #1 (web): Configure the web tier	TAGS: []
  pattern: ['web']
  hosts (2):
    web03.example.com
    web01.example.com

Operators are allowed in a limit file too, which is occasionally what you want and more often a sign the file should have been a plain list:

Read-only / Safea limit file containing a group and an exclusion— Real output from ansible-core 2.21.3. The file contained the two lines us_east and !canary, and the result is the same three hosts as the inline pattern.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit @wave2.limit --list-hosts

  play #1 (web): Configure the web tier	TAGS: []
  pattern: ['web']
  hosts (3):
    web04.example.com
    web03.example.com
    web02.example.com

A missing limit file is a hard error rather than an empty limit, which is the correct behaviour and worth knowing:

Read-only / Safethe file is not there— Real output from ansible-core 2.21.3, exit code 1. A typo in the filename stops the run instead of silently running unlimited - the opposite of what a naive implementation would do.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit @typo.limit --list-hosts

[ERROR]: Unable to find limit file b'/path/to/typo.limit'

The workflow this enables

Resolve the intended target and capture it: ansible -i inventory/ "<pattern>" --list-hosts | tail -n +2 | tr -d " " > change-OPS-5512.limit
Add a header comment naming the ticket, the date, and the pattern the list came from, so the file explains itself six months later.
Attach the file to the change record. It is the answer to "which hosts" in a form a reviewer can count and disagree with.
Run against the file rather than the pattern: --limit @change-OPS-5512.limit. The list was frozen at review time, so a host created since then is not in it.
Keep the file with the change record. After an incident it is the only artefact that says what the run was meant to touch, as distinct from what it did touch.

Step four is the one that matters for a dynamic inventory. A pattern re-resolves at execution time and can produce a different answer from the one that was reviewed; a limit file cannot. That is the closest a dynamic estate gets to the property a static inventory has for free.

Under the hood

--limit is stored as a subset on the play context, and applied when each play resolves its own pattern. Two consequences follow.

It applies to every play in the playbook, individually. A site.yml with plays for web, db and cache, run with --limit eu_west, narrows all three. Plays whose intersection with the limit is empty report skipping: no hosts matched and the run continues to the next play. This is why --limit on a large site playbook is safe rather than confusing: it does not need to know which plays are relevant.

It is applied after the pattern resolves, not before. So the pattern: line in --list-hosts output always shows the play’s own hosts: value, and the host list below it shows the result. When those two disagree with your expectation, the difference between them is exactly the limit.

The @file form is read once at startup and the file’s contents are treated as a comma-joined pattern, which is why groups, globs and operators all work inside it and why the file is not merely a list of hostnames. It also means the file is read from the controller’s filesystem at the moment the command starts — a file being written by another process at the same time is a race, and a generated limit file should be written to a temporary name and renamed into place.

What happens if the --limit matches nothing?

There are two different answers, and only one of them is loud. This is the single most important asymmetry in the lesson.

The limit matches no host in the inventory — a typo. Hard error, exit 1:

Read-only / Safea typo'd limit— Real output from ansible-core 2.21.3, exit code 1. web01.example.con does not exist. The run stops before doing anything.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit web01.example.con

[WARNING]: Could not match supplied host pattern, ignoring: web01.example.con
[ERROR]: Specified inventory, host pattern and/or --limit leaves us with no hosts to target.

The limit matches a real host that the play does not target. No error. Zero hosts. Exit 0:

Read-only / Safea valid host, outside the play's pattern— Real output from ansible-core 2.21.3, exit code 0. db01.example.com exists, but the play targets web, so the intersection is empty and the run reports a successful nothing.

$ ansible-playbook -i inventory/hosts.yml site.yml --limit db01.example.com

PLAY [Configure the web tier] **************************************************
skipping: no hosts matched

PLAY RECAP *********************************************************************

The first case fails closed and tells you. The second is a successful run that did nothing, and it is exactly what an operator produces by limiting to a database host while running the web playbook — a plausible mistake at three in the morning.

The lesson that follows is entirely about this second case and how to stop it being silent.

Knowledge check

Why this matters

--limit is where the plan for a change meets the command that performs it. Everything upstream — the groups, the pattern, the review — arrives at one flag typed by a person, often quickly, often at an inconvenient hour.

Two properties make that survivable. It can only narrow, so a mistake in the limit cannot reach hosts the play was not already aimed at. And a limit that matches nothing in the inventory is a hard error, so the commonest kind of mistake — a typo — stops the run rather than widening it.

The gap between those two is the case worth remembering: a limit that names something real but irrelevant produces a run that succeeds and does nothing. Combined with a limit file, which freezes a reviewed host list so the run cannot re-resolve into a different one, that gives you most of what a change process needs from targeting. The rest is proving the result before you commit to it, which is the next lesson.