Ansible Playbook --limit: Target Specific Hosts & Groups (Guide)

What Is --limit?

The --limit flag restricts playbook execution to specific hosts or groups from your inventory, without modifying the playbook or inventory file.

ansible-playbook playbook.yml --limit web-server-01

See also: Three options to Safely Limit Ansible Playbooks Execution to a Single Machine

Basic Syntax

# Single host
ansible-playbook playbook.yml --limit host1
# Multiple hosts (comma-separated)
ansible-playbook playbook.yml --limit host1,host2,host3
# Inventory group
ansible-playbook playbook.yml --limit webservers
# Multiple groups
ansible-playbook playbook.yml --limit "webservers:dbservers"

Host Patterns

Wildcard Patterns

# All web servers
ansible-playbook playbook.yml --limit "web-*"
# All servers in datacenter 1
ansible-playbook playbook.yml --limit "dc1-*"

Regex Patterns

Use ~ prefix for regex:

# Regex: hosts matching pattern
ansible-playbook playbook.yml --limit "~web-[0-9]+"
# Regex: hosts in specific range
ansible-playbook playbook.yml --limit "~web-(0[1-5])"

Exclude Hosts

Use ! to exclude:

# All webservers except web-03
ansible-playbook playbook.yml --limit "webservers:!web-03"
# All servers except database group
ansible-playbook playbook.yml --limit "all:!dbservers"

Intersection (AND Logic)

Use & for intersection:

# Hosts in BOTH webservers AND production
ansible-playbook playbook.yml --limit "webservers:&production"

Combined Patterns

# Webservers in production, excluding web-03
ansible-playbook playbook.yml --limit "webservers:&production:!web-03"

See also: Ansible playbook --limit: Run on Specific Hosts (Complete Guide)

Using --limit with retry Files

When a playbook fails, Ansible creates a .retry file listing failed hosts:

# Retry only failed hosts
ansible-playbook playbook.yml --limit @playbook.retry

Practical Examples

Rolling Deployments

# Deploy to first batch
ansible-playbook deploy.yml --limit "web-01,web-02"
# Verify, then deploy to second batch
ansible-playbook deploy.yml --limit "web-03,web-04"

Testing on Single Host

# Test playbook on one host first
ansible-playbook playbook.yml --limit web-01 --check --diff

Emergency Patching

# Patch only vulnerable hosts
ansible-playbook patch.yml --limit "vuln-host-01,vuln-host-02,vuln-host-03"

See also: Ansible ignore_errors: Error Handling Best Practices (Complete Guide)

In-Playbook Host Limiting

Using hosts Directive

---
- name: Run on specific hosts
  hosts: webservers
  tasks:
    - name: This runs on all webservers
      ansible.builtin.debug:
        msg: "Running on {{ inventory_hostname }}"

Using run_once

- name: Database migration (run once only)
  ansible.builtin.command: /app/migrate.sh
  run_once: true

Using when with inventory_hostname

- name: Special config for specific host
  ansible.builtin.template:
    src: special.conf.j2
    dest: /etc/app/special.conf
  when: inventory_hostname == 'web-01'

Using delegate_to

- name: Run on localhost regardless of target
  ansible.builtin.uri:
    url: "https://api.example.com/deploy"
    method: POST
  delegate_to: localhost
  run_once: true

Common Mistakes

Forgetting Quotes

# Wrong - shell interprets the !
ansible-playbook playbook.yml --limit webservers:!web-03
# Correct - quoted
ansible-playbook playbook.yml --limit "webservers:!web-03"

Limit vs Hosts Directive

--limit further restricts the hosts directive — it can't expand it:

# playbook.yml
- hosts: webservers
  tasks: [...]

# This won't run on db-01 even with --limit
# because db-01 isn't in the "webservers" group
ansible-playbook playbook.yml --limit db-01

FAQ

Can --limit override the hosts directive in a playbook?

No. --limit can only further restrict which hosts from the playbook's hosts directive are targeted. It cannot add hosts that aren't already matched by the hosts line.

How do I limit to a single host safely?

Use --limit hostname --check --diff first to preview changes, then remove --check to apply. This is the safest way to test playbooks on individual hosts before rolling out to the full inventory.

What happens if --limit matches no hosts?

Ansible skips the play and shows a warning. No tasks execute. You can force an error with any_errors_fatal: true or check with --list-hosts first.

How do I list which hosts --limit would target?

Use --list-hosts to preview without running:

ansible-playbook playbook.yml --limit "webservers:!web-03" --list-hosts

Related Articles

• Ansible Playbook Structure Guide • Ansible Inventory Guide • Ansible delegate_to Guide • Ansible run_once Guide