In Ansible 2.4, the include module is deprecated. In its place, it ships with two replacement modules, import_tasks and include_tasks. But they have very similar descriptions:

  • include_tasks: Includes a file with a list of tasks to be executed in the current playbook.
  • import_tasks: Imports a list of tasks to be added to the current playbook for subsequent execution.

When should I use the former, and when should I use the latter?

  • (Also: the deprecation warning refers to "dynamic" and "static" tasks. I read the docs but didn't understand them.) – Ben S Sep 24 '17 at 16:43
up vote 45 down vote accepted

There's quite a bit about this topic in the documentation:

The main difference is:

All import* statements are pre-processed at the time playbooks are parsed.
All include* statements are processed as they encountered during the execution of the playbook.

So import is static, include is dynamic.

From my experience, you should use import when you deal with logical "units". For example, separate long list of tasks into subtask files:

main.yml:

- import_tasks: prepare_filesystem.yml
- import_tasks: install_prerequisites.yml
- import_tasks: install_application.yml

But you would use include to deal with different workflows and take decisions based on some dynamically gathered facts:

install_prerequisites:

- include_tasks: prerequisites_{{ ansible_os_family | lower }}.yml
  • 5
    I found this link very useful: docs.ansible.com/ansible/latest/… It calls out a case where import and include behave differently - a 'when' conditional where the tasks in the file may change the criteria used to determine the import. With import_tasks, each task checks the criteria, so the behavior changes when the criteria changes. With include_tasks, the tasks are either present or not based on whether or not the condition was evaluated as true when the include_tasks statement was executed. If I understand well... – Ethel Evans Dec 6 '17 at 20:28
  • What was the behavior of include? If we were using include would import_tasks be the equivalent? – Andy Shinn Jan 18 at 20:27
  • include had static: yes (behaved like import_tasks), and static: no (like include_tasks). – Konstantin Suvorov Jan 19 at 6:28
  • What is the default for static? – Andy Shinn May 30 at 0:46
  • static is None by default: 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. – Konstantin Suvorov May 30 at 7:48

Imports are static, includes are dynamic. Imports happen at parsing time, includes at runtime.

Imports basically replace the task with the tasks from the file. There's no import_task at runtime. So, attributes like tags, and when (and most likely other attributes) are copied to every imported task.

includes are indeed executed. tags and when of an included task apply only to the task itself.

Tagged tasks from an imported file get executed if import task is untagged. No tasks is executed from an included file if include task is untagged.

All tasks from an imported file get executed if import task is tagged. Only tagged tasks from an included file get executed if include task is tagged.

Limitations of imports:

  • can't be used with with_* or loop attributes
  • can't import a file, which name depends on a variable

Limitations of includes:

  • --list-tags doesn't show tags from included files
  • --list-tasks doesn't show tasks from included files
  • you cannot use notify to trigger a handler name which comes from inside a dynamic include
  • you cannot use --start-at-task to begin execution at a task inside a dynamic include

More on it here and here.

For me that basically comes down to the fact that imports can't be used with loop attributes.

import would certainly fail in cases like this:

# playbook.yml
- import_tasks: set-x.yml
  when: x is not defined

# set-x.yml
- set_fact
  x: foo
- debug:
  var: x

debug is not executed, since it inherits when from import_tasks task. So, no importing task files that change variables used in import's when attribute.

I had a policy to start with imports, but once I need an include make sure nothing is imported by that included file or the files it includes. But that's pretty damn hard to maintain. And it's still not clear if it'll protect me from troubles. That's mixing includes and imports which they don't recommend.

I can't use only imports, since I occasionally need to loop include tasks. I could probably switch to only includes. But I decided to switch to imports everywhere except for the cases where the task is supposed to be run several times. I decided to experience all those tricky edge cases first-hand. Maybe there won't be any in my playbooks. Or hopefully I'll find a way to make it work.

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.