include – Include a play or task list — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# include – Include a play or task list

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Status

## Synopsis

- Includes a file with a list of plays or tasks to be executed in the current playbook.
- Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks normally run (in play).
- Before Ansible 2.0, all includes were ‘static’ and were executed when the play was compiled.
- Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each inherited task.
- Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped, skipped and use variables from any source. Ansible tries to auto detect this, but you can use the `static` directive (which was added in Ansible 2.1) to bypass autodetection.
- This module is also supported for Windows targets.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
free-form - |  | This module allows you to specify the name of the file directly without any other options.

## Notes

Note

- This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
- Include has some unintuitive behaviours depending on if it is running in a static or dynamic in play or in playbook context, in an effort to clarify behaviours we are moving to a new set modules (include_tasks, include_role, import_playbook, import_tasks) that have well established and clear behaviours.
- This module will still be supported for some time but we are looking at deprecating it in the near future.

## See Also

See also

import_playbook – Import a playbook
  The official documentation on the import_playbook module.
import_role – Import a role into a play
  The official documentation on the import_role module.
import_tasks – Import a task list
  The official documentation on the import_tasks module.
include_role – Load and execute a role
  The official documentation on the include_role module.
include_tasks – Dynamically include a task list
  The official documentation on the include_tasks module.
Including and Importing
  More information related to including and importing playbooks, roles and tasks.

## Examples

    - hosts: localhost
      tasks:
        - debug:
            msg: play1

    - name: Include a play after another play
      include: otherplays.yaml

    - hosts: all
      tasks:
        - debug:
            msg: task1

        - name: Include task list in play
          include: stuff.yaml

        - debug:
            msg: task10

    - hosts: all
      tasks:
        - debug:
            msg: task1

        - name: Include task list in play only if the condition is true
          include: "{{ hostvar }}.yaml"
          static: no
          when: hostvar is defined

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Ansible Core Team (@ansible)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.