ansible.builtin.include_vars module – Load variables from files, dynamically within a task — Ansible Documentation (2022)

'; // Create a banner if we're not on the official docs site if ( == "") { document.write('

'); } // Create a banner current_url_path = window.location.pathname; var important = false; var msg = '

'; if (startsWith(current_url_path, "/ansible-core/")) { msg += 'You are reading documentation for Ansible Core, which contains no plugins except for those in ansible.builtin. For documentation of the Ansible package, go to the latest documentation.'; } else if (startsWithOneOf(current_url_path, ["/ansible/latest/", "/ansible/6/"])) { /* temp extra banner to advertise AnsibeFest2021 */ banner += extra_banner; msg += 'You are reading the latest (stable) community version of the Ansible documentation. Red Hat subscribers, select 2.9 in the version selection to the left for the most recent Red Hat release.'; } else if (startsWith(current_url_path, "/ansible/2.9/")) { msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select latest from the version selector to the left for the most recent community version.'; } else if (startsWith(current_url_path, "/ansible/devel/")) { /* temp extra banner to advertise AnsibleFest2021 */ banner += extra_banner; /* temp banner to advertise survey important = true; msg += 'Please take our Docs survey before December 31 to help us improve Ansible documentation.'; */ msg += 'You are reading the devel version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest (stable) released version.'; } else { msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest (stable) released version.'; } msg += '

'; banner += '

'; document.write(banner);


This module is part of ansible-core and included in all Ansibleinstallations. In most cases, you can use the shortmodule nameinclude_vars even without specifying the collections: keyword.However, we recommend you use the FQCN for easy linking to themodule documentation and to avoid conflicting with other collections that may havethe same module name.

New in version 1.4: of ansible.builtin

  • Synopsis

  • Parameters

  • Attributes

  • See Also

  • Examples

  • Return Values


  • Loads YAML/JSON variables dynamically from a file or directory, recursively, during task runtime.

  • If loading a directory, the files are sorted alphabetically before being loaded.

  • This module is also supported for Windows targets.

  • To assign included variables to a different host than inventory_hostname, use delegate_to and set delegate_facts=yes.


This module has a corresponding action plugin.






added in 2.2 of ansible.builtin

When using dir, this module will, by default, recursively go through each sub directory and load up the variables. By explicitly setting the depth, this module will only go as deep as the depth.

Default: 0

(Video) Variables and Variable Files in Ansible - Aruba Bots Ansible Series 03



added in 2.2 of ansible.builtin

The directory name from which the variables should be loaded.

If the path is relative and the task is inside a role, it will look inside the role’s vars/ subdirectory.

If the path is relative and not inside a role, it will be parsed relative to the playbook.


list / elements=string

added in 2.3 of ansible.builtin

List of file extensions to read when using dir.

Default: [“json”, “yaml”, “yml”]



added in 2.2 of ansible.builtin

The file name from which variables should be loaded.

If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.

Limit the files that are loaded within any directory to this regular expression.



This module allows you to specify the ‘file’ option directly without any other options.

There is no ‘free-form’ option, this is just an indicator, see example below.



added in 2.12 of ansible.builtin

(Video) How Ansible Variables work in a Playbook | Hands-on using Ansible Variables | #Valaxy

If set to merge, merges existing hash variables instead of overwriting them.

If omitted null, the behavior falls back to the global hash_behaviour configuration.


  • replace

  • merge


list / elements=string

added in 2.2 of ansible.builtin

List of file names to ignore.



added in 2.7 of ansible.builtin

Ignore unknown file extensions within the directory.

This allows users to specify a directory containing vars files that are intermingled with non-vars files extension types (e.g. a directory with a README in it and vars files).


  • no ← (default)

  • yes



added in 2.2 of ansible.builtin

The name of a variable into which assign the included vars.

If omitted (null) they will be made top level vars.






Support: partial

While the action plugin does do some of the work it relies on the core engine to actually create the variables, that part cannot be overriden

Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller


(Video) Ansible Host Variables and Group Variables | #Ansible #FullCourse | techbeatly

Support: none

Supports being used with the async keyword


Support: none

Is usable alongside become keywords


Support: none

Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations

Conditionals will work as if run_once is being used, variables used will be from the first available host

This action will not work normally outside of lockstep strategies


Support: none

These tasks ignore the loop and with_ keywords


Support: full

Can run in check_mode and return changed status prediction without modifying target


Support: none

Uses the target’s configured connection information to execute code on it


Support: partial

While parts of this action are implemented in core, other parts are still available as normal plugins and can be partially overridden

This is a ‘core engine’ feature and is not implemented like most task actions, so it is not overridable in any way via the plugin system.


Support: partial

while variable assignment can be delegated to a different host the execution context is always the current inventory_hostname

connection variables, if set at all, would reflect the host it would target, even if we are not connecting at all in this case

Can be used in conjunction with delegate_to and related keywords


(Video) Monitoring as code with Sensu + Ansible Webinar

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode


Support: none

The action is not subject to conditional execution so it will ignore the when: keyword



Target OS/families that can be operated against


Support: full

Allows for the ‘tags’ keyword to control the selection of this action for execution


Support: full

Denotes if this action objeys until/retry/poll keywords

See Also

See also


The official documentation on the ansible.builtin.set_fact module.

Controlling where tasks run: delegation and local actions

More information related to task delegation.


- name: Include vars of stuff.yaml into the 'stuff' variable (2.2). ansible.builtin.include_vars: file: stuff.yaml name: stuff- name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2) ansible.builtin.include_vars: file: contingency_plan.yaml name: plans when: x == 0- name: Load a variable file based on the OS type, or a default if not found. Using free-form to specify the file. ansible.builtin.include_vars: "{{ lookup('ansible.builtin.first_found', params) }}" vars: params: files: - '{{ansible_distribution}}.yaml' - '{{ansible_os_family}}.yaml' - default.yaml paths: - 'vars'- name: Bare include (free-form) ansible.builtin.include_vars: myvars.yaml- name: Include all .json and .jsn files in vars/all and all nested directories (2.3) ansible.builtin.include_vars: dir: vars/all extensions: - 'json' - 'jsn'- name: Include all default extension files in vars/all and all nested directories and save the output in test. (2.2) ansible.builtin.include_vars: dir: vars/all name: test- name: Include default extension files in vars/services (2.2) ansible.builtin.include_vars: dir: vars/services depth: 1- name: Include only files matching bastion.yaml (2.2) ansible.builtin.include_vars: dir: vars files_matching: bastion.yaml- name: Include all .yaml files except bastion.yaml (2.3) ansible.builtin.include_vars: dir: vars ignore_files: - 'bastion.yaml' extensions: - 'yaml'- name: Ignore warnings raised for files with unknown extensions while loading (2.7) ansible.builtin.include_vars: dir: vars ignore_unknown_extensions: True extensions: - '' - 'yaml' - 'yml' - 'json'

Return Values

Common return values are documented here, the following are the fields unique to this module:




list / elements=string

added in 2.4 of ansible.builtin

A list of files that were successfully included

Returned: success

Sample: [“/path/to/file.json”, “/path/to/file.yaml”]


  • Allen Sanabria (@linuxdynasty)

Collection links

Issue Tracker Repository (Sources) Communication


1. Configure Ansible for VMware - ansible collection community.vmware
(Ansible Pilot)
2. Ansible Advanced Template Loops Tutorial - Use Loop Vars in Your Templates
(Percy Grunwald from TopTechSkills)
3. Ansible Advance Complete Refrence Tutorials - Oct - 2020 - Session 6 - By DevOpsSchool
(Artificial Intelligence Universe)
4. Ansible Advance Complete Refrence Tutorials - Oct - 2020 - Session 7 - By DevOpsSchool
(Artificial Intelligence Universe)
5. Ansible Crash Course For Beginners | Ansible Tutorial | What Is Ansible? | DevOps Tools - Part - 08

You might also like

Latest Posts

Article information

Author: Jamar Nader

Last Updated: 07/22/2022

Views: 6306

Rating: 4.4 / 5 (75 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Jamar Nader

Birthday: 1995-02-28

Address: Apt. 536 6162 Reichel Greens, Port Zackaryside, CT 22682-9804

Phone: +9958384818317

Job: IT Representative

Hobby: Scrapbooking, Hiking, Hunting, Kite flying, Blacksmithing, Video gaming, Foraging

Introduction: My name is Jamar Nader, I am a fine, shiny, colorful, bright, nice, perfect, curious person who loves writing and wants to share my knowledge and understanding with you.