Ansible vars_files: Load Variables from External YAML Files (Guide)
By Luca Berton · Published 2024-01-01 · Category: troubleshooting
Complete guide to Ansible vars_files. Load variables from external YAML files, use with Ansible Vault encryption, organize by environment, and handle conditional variable loading with practical examples.
The vars_files directive loads variables from external YAML files into your Ansible playbooks. It keeps playbooks clean, enables variable reuse across plays, and is essential for managing encrypted secrets with Ansible Vault.
Basic Syntax
Multiple Files
List multiple files — they're loaded in order, with later files overriding earlier ones:
Dynamic File Names
Use variables in filenames for environment-specific configs:
vars_files with Ansible Vault
The most common pattern — keep secrets in encrypted files:
Run with vault password:
Optional Files (Avoid Errors)
If a file might not exist, use a list-of-lists pattern or include_vars with ignore_errors:
vars_files vs Other Variable Methods
| Method | When Loaded | Scope | Dynamic Filenames | Use For | |--------|------------|-------|-------------------|---------| | vars_files | Play start | Play | ✅ | External variable files, vault secrets | | vars: | Play start | Play | N/A (inline) | Small, inline variable sets | | include_vars | Task runtime | Task onwards | ✅ | Conditional loading, dynamic files | | group_vars/ | Inventory parse | Group | ❌ (directory-based) | Environment/group config | | host_vars/ | Inventory parse | Host | ❌ (directory-based) | Host-specific overrides | | defaults/main.yml | Role loading | Role | ❌ | Role default values |
Project Structure Example
Precedence
vars_files has the same precedence as vars_prompt (level 14 in Ansible's 22-level hierarchy): • Higher than: group_vars, host_vars, play vars, role defaults • Lower than: role vars, block vars, task vars, set_fact, extra vars
FAQ
What does vars_files do in Ansible?
vars_files loads variables from one or more external YAML files at the beginning of a play. The variables become available to all tasks, roles, and templates within that play.
What is the difference between vars_files and include_vars?
vars_files loads at play start (before any tasks run) and is declared at the play level. include_vars is a task-level module that loads variables at runtime — useful for conditional loading and dynamic filenames based on gathered facts.
Can I use vars_files with Ansible Vault?
Yes, this is the most common pattern. List your vault-encrypted file in vars_files and run the playbook with --ask-vault-pass or --vault-password-file. Ansible decrypts transparently.
What happens if a vars_file doesn't exist?
Ansible throws an error and stops. To handle optional files, use a list-of-lists syntax [preferred.yml, fallback.yml] or use include_vars with ignore_errors: true.
Can I use variables in vars_files paths?
Yes, you can use Jinja2 variables in filenames: vars_files: ["vars/{{ env }}.yml"]. The variable must be defined before vars_files is processed (e.g., via extra vars, inventory vars, or earlier in the list).
Conclusion • vars_files is the cleanest way to externalize playbook variables • Combine with Vault for encrypted secrets • Use dynamic filenames for environment/OS-specific configs • Order matters — later files override earlier ones • Use include_vars when you need runtime conditional loading
Related Articles • Ansible Variable Precedence: Complete Guide • Ansible Vault: Encrypt Secrets • Ansible Extra Vars: Pass Variables via Command Line • Ansible set_fact Module: Dynamic Variables
Category: troubleshooting