Ansible Import_Playbook

When we think about Ansible, we often picture its power to automate the configuration management, application deployment, and other DevOps tasks.

However, when automating tasks, we might encounter such instances where we need to reuse specific parts of a single or even multiple playbooks. Hence, instead of copying and pasting the sections between playbooks, splitting the complex playbooks into smaller, more manageable pieces that we can import as required can be essential.

This is where the Ansible import_playbook directive comes into play.

The import_playbook directive allows us to load and execute another playbook within a playbook which lets us structure and modularize the Ansible projects for easier maintenance and readability.

In this tutorial, we will explore the workings of the import_playbook directive to learn how to break and reuse the other playbook sections within our current playbook.


To follow along, ensure that you have the following:

  • Basic understanding of Ansible and how to write basic playbooks
  • Installed Ansible on your local machine or control node
  • One or more target machines to run the tasks on

How the Import_Playbook Directive Works

The import_playbook is not technically an Ansible module but a directive. This means that we use it at the top level of a playbook, not inside a task or play.

The following demonstrates the basic syntax of the import_playbook directive:

- import_playbook: <playbook_filename.yml>

Let us explore some basic examples on how to work with this directive.

Example 1:

Let us start by defining two playbooks that install a web server and another that installs a database server.

The first playbook is the “webserver.yaml” file as defined in the following:

- hosts: web
    - name: Install httpd
        name: httpd
        state: present

The second playbook is the “database.yaml” file as defined in the following:

- hosts: database
    - name: Install mariadb
        name: mariadb-server
        state: present

Once these playbooks are defined, we can learn how to import and reuse them as necessary.

Example 2: Basic Usage

To use the webserver and database playbooks, we can use the “import_playbook” directive with the path to the playbook that we wish to import as follows:

- import_playbook: web.yml
- import_playbook: database.yml

If we run the “main.yml” playbook, it execues both the “webserver.yaml” and “database.yaml” sequentially.

Conditional Playbook Import

Suppose we have two environments: development and production.

We can use different playbooks for each environment and conditionally import them based on a variable as demonstrated in the following example:


- hosts: dev
    - debug:
        msg: "Deploying to Development Environment"


- hosts: prod
    - debug:
        msg: "Deploying to Production Environment"

Finally, to conditionally use them, we can import them as shown in the “main.yaml” file as follows:

- name: Check Environment
  hosts: localhost
    - name: Set environment fact
        env: "{{ env_variable }}"
- import_playbook: dev.yml
  when: env == "development"
- import_playbook: prod.yml
  when: env == "production"

We can now run the playbook that specifies the environment as shown in the following command:

$ ansible-playbook main.yml -e env_variable=development

Import Playbook from the Collection

We can also import a playbook from a given collection as shown in the following example:

- name: Include a playbook from a collection
  ansible.builtin.import_playbook: namespace.collection.playbook_name

There you have it!

When to Use the Import_Playbook

Although the import_playbook is very useful, there are some situations in which it’s most applicable. For example:

  • Modularization – Break an extensive playbook into smaller logical pieces to improve readability and maintenance.
  • Reusability – Use a standard set of tasks or plays across multiple projects without duplicating the code.
  • Conditional Execution – Run specific playbooks based on conditions.

NOTE: The import_playbook and include_tasks are different things that carry out different actions. The import_playbook is useful when importing the entire playbooks, while the include_tasks is for task files within a play.


The import_playbook directive is a powerful tool for structuring and organizing the Ansible playbooks. As shown in this tutorial, you can use it to ensure that your automation is modular, maintainable, and efficient.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list