Ansible extra vars (-e): Pass Variables from Command Line (Complete Guide)

Ansible extra vars (-e): Pass Variables from Command Line (Complete Guide)

Extra vars (--extra-vars or -e) are the highest precedence variables in Ansible, passed directly from the command line. They override every other variable source — inventory, group_vars, role defaults, and playbook vars.

See also: AAP 2.6 ansible-navigator: Modern CLI for Automation Development

Basic Usage

# Single variable
ansible-playbook deploy.yml -e "env=production"
# Multiple variables
ansible-playbook deploy.yml -e "env=production version=2.5.0 region=us-east-1"

In your playbook:

---
- name: Deploy application
  hosts: webservers
  tasks:
    - name: Deploy version
      ansible.builtin.debug:
        msg: "Deploying v{{ version }} to {{ env }} in {{ region }}"

Variable Formats

Key=Value (Simple)

ansible-playbook site.yml -e "username=admin debug_mode=true count=5"

JSON String

# JSON object
ansible-playbook site.yml -e '{"env": "production", "features": ["auth", "logging"]}'
# JSON with nested values
ansible-playbook site.yml -e '{"database": {"host": "db01", "port": 5432}}'

YAML String

ansible-playbook site.yml -e '{env: production, debug: false}'

Variable File (@filename)

# Load from YAML file
ansible-playbook site.yml -e @vars/production.yml
# Load from JSON file
ansible-playbook site.yml -e @vars/deploy-config.json

vars/production.yml:

env: production
db_host: db.prod.example.com
db_port: 5432
app_workers: 8
features:
  - auth
  - caching
  - monitoring

Multiple -e Flags

# Combine multiple sources (later values override earlier)
ansible-playbook site.yml \
  -e @vars/defaults.yml \
  -e @vars/production.yml \
  -e "version=2.5.0"

See also: AWX-TUI: A Terminal User Interface for AWX — Install and Getting Started Guide

Variable Precedence

Extra vars have the highest precedence (position 22 of 22). They override everything:

1.  role defaults (lowest)
2.  inventory variables
3.  group_vars/all
4.  group_vars/group
5.  host_vars/host
6.  play vars
7.  role vars
...
22. extra vars (-e) ← HIGHEST

This makes -e perfect for one-time overrides without modifying files.

Common Patterns

Environment Promotion

# Deploy to staging
ansible-playbook deploy.yml -e "env=staging"
# Deploy to production
ansible-playbook deploy.yml -e "env=production"

# deploy.yml
- hosts: "{{ env }}_servers"
  vars_files:
    - "vars/{{ env }}.yml"
  tasks:
    - name: Deploy to {{ env }}
      ansible.builtin.include_role:
        name: deploy

Version Pinning

ansible-playbook deploy.yml -e "app_version=2.5.0 rollback=false"

Target Host Override

# Run on specific host(s)
ansible-playbook site.yml -e "target_hosts=web01"

- hosts: "{{ target_hosts | default('all') }}"
  tasks:
    - ansible.builtin.debug:
        msg: "Running on {{ inventory_hostname }}"

Boolean Flags

# Enable debug mode
ansible-playbook site.yml -e "debug_mode=true force_restart=yes"
# Dry run
ansible-playbook site.yml -e "dry_run=true"

- name: Restart service
  ansible.builtin.systemd:
    name: myapp
    state: restarted
  when: force_restart | default(false) | bool

Pass Lists and Dictionaries

# List
ansible-playbook site.yml -e '{"packages": ["nginx", "postgresql", "redis"]}'
# Dictionary
ansible-playbook site.yml -e '{"db": {"host": "db01", "port": 5432, "name": "myapp"}}'

See also: Ansible Creator CLI: Scaffold Collections, Roles & Projects (v26.4.0)

Extra Vars with Ad-Hoc Commands

# ansible command with extra vars
ansible all -m debug -a "msg={{ greeting }}" -e "greeting='Hello World'"
# Use with shell module
ansible webservers -m shell -a "echo {{ message }}" -e "message='Maintenance in 5 minutes'"

Extra Vars with ansible-pull

ansible-pull -U https://github.com/org/playbooks.git -e "env=production node_type=web"

Secrets and Vault with Extra Vars

# Pass vault-encrypted variable file
ansible-playbook deploy.yml -e @vars/secrets.yml --ask-vault-pass
# Combine regular and encrypted vars
ansible-playbook deploy.yml \
  -e @vars/production.yml \
  -e @vars/vault-production.yml \
  --vault-password-file ~/.vault_pass

Dynamic Extra Vars

From Shell Commands

# Current git commit
ansible-playbook deploy.yml -e "git_sha=$(git rev-parse --short HEAD)"
# Current timestamp
ansible-playbook deploy.yml -e "deploy_time=$(date -u +%Y%m%d_%H%M%S)"
# From environment variable
ansible-playbook deploy.yml -e "api_key=${API_KEY}"

From Script Output

# From jq/API
ansible-playbook deploy.yml -e "$(curl -s https://api.example.com/config | jq -r 'to_entries | map("\(.key)=\(.value)") | join(" ")')"

Default Values for Extra Vars

Always provide defaults in playbooks for optional extra vars:

- hosts: "{{ target_hosts | default('webservers') }}"
  vars:
    app_version: "{{ version | default('latest') }}"
    worker_count: "{{ workers | default(4) }}"
    debug_enabled: "{{ debug | default(false) | bool }}"
  tasks:
    - ansible.builtin.debug:
        msg: "Version: {{ app_version }}, Workers: {{ worker_count }}"

FAQ

What are extra vars in Ansible?

Extra vars (-e or --extra-vars) are variables passed from the command line when running ansible-playbook. They have the highest precedence in Ansible's variable hierarchy, overriding all other variable sources including inventory, group_vars, and playbook vars.

How do I pass a variable from the command line in Ansible?

Use -e flag: ansible-playbook playbook.yml -e "variable=value". For multiple variables: -e "var1=value1 var2=value2". For complex data, use JSON: -e '{"key": "value"}'. For files: -e @vars.yml.

Can I pass a list or dictionary as an extra var?

Yes, use JSON format: -e '{"my_list": ["a", "b", "c"]}' or -e '{"my_dict": {"key": "value"}}'. Key=value format only works for simple strings.

Do extra vars override all other variables?

Yes. Extra vars have the absolute highest precedence in Ansible (position 22 of 22). They override role defaults, inventory vars, group_vars, host_vars, play vars, role vars, and everything else.

How do I pass a variable file with extra vars?

Use the @ prefix: -e @vars/production.yml. The file can be YAML or JSON. You can combine multiple files and inline values: -e @defaults.yml -e @prod.yml -e "version=2.0".

Conclusion

Extra vars (-e) are the most powerful way to parameterize Ansible playbooks at runtime. Use them for environment promotion, version pinning, and one-time overrides. Always provide default() values for optional extra vars to make playbooks usable with or without command-line arguments.

Related Articles

• Ansible Variables: Complete Guide • Ansible Variable Precedence: 22 Levels Explained • Ansible Vault: Encrypt Sensitive Data • Ansible Magic Variables: Complete Reference