include vs import

import_* and include_* both pull in another file of tasks, a role, or a playbook, and they look interchangeable until they aren't — they are the single most confused pair in Ansible. import_* is static: the content is read and inlined at parse time, before the play runs. include_* is dynamic: the content is pulled in at run time, when execution reaches that line.

That one difference — parse time versus run time — decides how tags, loops, and when behave on the included content. Get it wrong and you produce a playbook that runs the wrong tasks, loops once instead of per item, or ignores your --tags entirely. The whole topic is one distinction and its three consequences.

Parse Time versus Run Time

import_tasks and import_playbook are processed when Ansible reads the playbook, before anything executes — so the imported tasks exist as real, individual tasks in the plan from the start. include_tasks and include_role are processed when the play reaches them at run time, so their tasks do not exist until that moment of execution. That is the entire root cause: a statically imported task is visible before the run; a dynamically included one is invisible until the line is hit.

The Tags Consequence

Tags on an import propagate to every imported task — they are inlined at parse time, so --list-tags sees them and --tags can select them. A tag on an include applies only to the include statement itself, and --tags cannot select tasks inside a dynamic include, because those tasks do not exist yet at selection time. This is the classic trap: include_tasks: deploy.yml plus --tags deploy runs nothing, because there is nothing tagged deploy in the plan when the filter is applied.

The Loop Consequence

You can loop: over an include_tasks to run a whole task file once per item, because the include is evaluated at run time and the loop drives repeated evaluation. You cannot loop an import_tasks — it is inlined at parse time, before any loop exists to drive it, so Ansible rejects a loop on an import outright with a parse-time error: You cannot use loops on 'import_tasks' statements. You should use 'include_tasks' instead. When you need a task file applied per element of a list, the include is the only form that works.

- name: Configure each Larkspur site from one task file
  ansible.builtin.include_tasks: configure_site.yml
  loop: "{{ larkspur_sites }}"
  loop_control:
    loop_var: site

Each iteration pulls configure_site.yml in fresh with site bound to the current entry. Swap include_tasks for import_tasks here and the file runs once with whatever site happens to be — the loop is ignored because the import was already resolved before the loop could matter.

The when Consequence

when on an import is copied onto every imported task individually, and each one is then evaluated per host — the condition is distributed, not applied once. when on an include gates the single include statement, deciding once whether to pull the file in at all. Same keyword, different reach: an import with a when stamps the condition onto each inner task, while an include with a when is a single yes-or-no on the whole file. The surprise is usually a set_fact inside an imported file that you expected to skip wholesale but which gets the condition stamped on it individually instead.

Choosing Between Them

Use import for static structure you always run and want visible to --tags and --list-tasks — fixed scaffolding that never changes shape between runs. Use include when the file to pull in, or whether to pull it in, depends on run-time data: a variable computed earlier, a loop over a list, or a registered result. The rule of thumb is simple — when the structure is static, import; the moment you need a loop or a run-time-computed target, include.