Ansible Include and Import

Large playbooks grow messy. A single file with two hundred tasks is hard to read, test, and share. Splitting work into smaller files fixes the problem, and Ansible offers two families of keywords to pull those files back together: import and include. Imagine a cookbook that says "prepare the sauce, see page 12". The cook flips to page 12 and follows it. The keywords act as that page reference. The two families differ in when Ansible reads the referenced page.

Static Versus Dynamic

FamilyKeywordsProcessing TimeType
Importimport_tasks, import_playbook, import_rolePlaybook parse time, before the runStatic
Includeinclude_tasks, include_role, include_varsRun time, when execution reaches the lineDynamic

Diagram: Two Reading Styles

  IMPORT (static)                    INCLUDE (dynamic)

  site.yml                           site.yml
     │ import_tasks: db.yml             │ include_tasks: db.yml
     ▼                                  ▼
  Ansible reads db.yml               Ansible runs earlier tasks
  BEFORE the run starts              ...reaches the include line...
     │                                  │
     ▼                                  ▼
  One big merged task list           Ansible loads db.yml NOW
  is executed                        and runs it

Import Tasks

Store a group of tasks in a separate file. Keep the file free of play headers, since it holds only a task list.

# tasks/database.yml
- name: Install MariaDB
  ansible.builtin.package:
    name: mariadb-server
    state: present

- name: Start MariaDB
  ansible.builtin.service:
    name: mariadb
    state: started
    enabled: true
# site.yml
- hosts: dbservers
  become: true
  tasks:
    - ansible.builtin.import_tasks: tasks/database.yml

Include Tasks with a Loop or Condition

Dynamic includes support loops and conditions that depend on values created during the run.

- name: Configure each site
  ansible.builtin.include_tasks: site.yml
  loop:
    - shop
    - blog
    - docs
  loop_control:
    loop_var: site_name

The file site.yml runs three times, and the variable site_name holds a different value on each pass.

- name: Pick tasks by operating system
  ansible.builtin.include_tasks: "{{ ansible_os_family }}.yml"

This pattern loads Debian.yml or RedHat.yml based on a fact.

Import Playbook

The import_playbook keyword assembles a master playbook from smaller ones. Place the keyword at the top level, outside any play.

# site.yml
- import_playbook: webservers.yml
- import_playbook: dbservers.yml
- import_playbook: loadbalancers.yml

Run ansible-playbook site.yml to build the whole environment, or run webservers.yml alone for a targeted change.

Import Role and Include Role

tasks:
  - ansible.builtin.import_role:
      name: common

  - ansible.builtin.include_role:
      name: monitoring
    when: enable_monitoring | default(false)

The include_role keyword allows a condition to decide whether the role runs at all.

Behavior Differences

  • A condition on import_tasks applies to every imported task individually
  • A condition on include_tasks applies once to the include line
  • Tags on an import apply to all imported tasks, and tags on an include apply only to the include line
  • --list-tasks shows imported tasks but hides dynamically included ones
  • --start-at-task works with imports and fails with includes

Choosing Between the Two

Choose imports for fixed structure that needs clear previews, tags, and predictable behavior. Choose includes when a loop, a fact, or a runtime variable decides what loads. Avoid mixing both styles for the same file inside one project, because the mixed behavior confuses readers.

Try This

Move two tasks from a playbook into tasks/common.yml and load them with import_tasks. Run ansible-playbook site.yml --list-tasks and notice the tasks appear. Switch to include_tasks, run the same command, and observe the include line without the inner tasks.

Summary

Import keywords load files during parsing and produce a predictable, previewable task list. Include keywords load files during execution and respond to loops, conditions, and runtime data. Use import_playbook to compose a master playbook. Pick the style that matches the need, and keep each project consistent.