ansible-playbook(1)
Execute Ansible playbooks to automate infrastructure configuration and orchestration across multiple hosts.
Synopsis
ansible-playbook [OPTION]... PLAYBOOK.yml [PLAYBOOK.yml ...]Description
ansible-playbook runs one or more YAML playbook files to execute defined tasks, roles, and handlers across inventory hosts. Playbooks are the primary way to use Ansible for configuration management, deployment, and orchestration workflows.
The command reads playbook definitions, connects to target hosts via SSH (or other configured connection methods), and executes plays and tasks in sequence. Handlers are triggered by task changes, and variables can be dynamically set from inventory, command-line, or task results.
Exit codes indicate success (0), general failures (1), or host-specific failures (2-250).
Common options
| Flag | What it does |
|---|---|
-i INVENTORY | Specify inventory file or directory (hosts, hosts.ini, hosts/dynamic.py) |
-l SUBSET | Limit execution to hosts matching pattern (e.g., 'webservers', 'host1,host2') |
-e VARS | Set extra variables as JSON or key=value pairs (repeatable) |
-k | Prompt for SSH password for all hosts |
-K | Prompt for privilege escalation (sudo) password |
-u USERNAME | Connect as specific SSH user (overrides inventory setting) |
-b | Enable privilege escalation (become/sudo) for all tasks |
-v | Increase verbosity (-vv, -vvv, -vvvv for more detail) |
-C | Run in check mode (dry-run; shows what would change without applying) |
-t TAGS | Only run tasks tagged with specified tags (comma-separated) |
--syntax-check | Validate playbook YAML syntax without executing |
-f FORKS | Number of parallel processes (default 5) |
Examples
Execute site.yml playbook against all inventory hosts
ansible-playbook site.ymlRun deploy.yml only on hosts in webservers group from hosts.ini inventory
ansible-playbook -i hosts.ini deploy.yml -l webserversExecute playbook with extra variables passed on command line
ansible-playbook site.yml -e env=production -e version=2.1Run as deploy user with sudo, prompting for sudo password
ansible-playbook playbook.yml -u deploy -b -KDry-run playbook in check mode with verbose output to preview changes
ansible-playbook -C -v site.ymlExecute only tasks tagged with 'config' label
ansible-playbook site.yml -t configValidate playbook syntax without connecting to hosts
ansible-playbook multi-play.yml --syntax-checkRun against localhost using local connection plugin (comma required for single host)
ansible-playbook site.yml -i 127.0.0.1, -c local