# ansible / configuration / handlers

State-Aware Execution with Handlers

A handler is a special task in Ansible that runs only when another task explicitly notifies it. Handlers prevent unnecessary actions by running only when a genuine change occurs on the system.

See How it Works →Jump to Examples

Execution Condition✓

TaskUpdate configuration file

Conditionchanged

ActionNotify Handler

notify

Trigger

Once

Execution

# concept

Why do we need Handlers?

Suppose a playbook updates a configuration file. If the file changes, the service should restart to apply the new settings. If the file does not change, restarting the service is completely unnecessary.

common use cases

When to use them

• Restart a service after updating its configuration.
• Reload a service after changing a configuration file.
• Execute a script only after a file has changed.

THE SOLUTION

A handler solves this problem perfectly by running only when a standard task reports a changed state.

# lifecycle

How a Handler Works & Syntax

The Execution Flow

1. Task Execution
A standard task runs (e.g., copying a file).
2. Condition Check

If File Changed → Sends a notification to the handler.

If No Change → No notification is sent.
3. Queueing
Tasks finish executing in their normal top-to-bottom order.
4. Handler Execution
After all tasks successfully complete, the notified Handler executes.

Basic SyntaxYAML

1 2 3 4 5 6 7 8 9 10 11

tasks:
  - name: Task Name
    module:
      ...
    notify:
      - Handler Name

handlers:
  - name: Handler Name
    module:
      ...

# demonstration

Practical Examples

example 1

Basic Handler Execution

We create an employee file using a Jinja2 template. If the file is created or changed, a message is displayed.

employee.j2TEMPLATE

Employee Name : {{ empname }}
Age : {{ age }}
Role : {{ role }}

playbook.ymlYAML

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

---
- name: Handler Example
  hosts: localhost
  become: yes

  vars:
    empname: shan
    age: 27
    role: DevOps Engineer

  tasks:
    - name: Create employee file
      template:
        src: employee.j2
        dest: /tmp/employee.txt
      notify:
        - Display Message

  handlers:
    - name: Display Message
      debug:
        msg: "Employee file was updated successfully."

First Run Output

# The template creates the file for the first time.

TASK [Create employee file]

changed

RUNNING HANDLER [Display Message]

ok: Employee file was updated successfully.

Second Run Output

# No variables or content changed.

TASK [Create employee file]

# The handler DOES NOT execute.

example 2

Multiple Tasks, One Handler

What happens if multiple tasks notify the exact same handler? If both tasks change their files:

Task 1 → Notify Show Message
Task 2 → Notify Show Message

The handler runs only once after all tasks complete.

multiple_notify.ymlYAML

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

tasks:
  - name: Create employee file
    template:
      src: employee.j2
      dest: /tmp/employee.txt
    notify: Show Message

  - name: Create department file
    copy:
      content: "Department: DevOps"
      dest: /tmp/department.txt
    notify: Show Message

handlers:
  - name: Show Message
    debug:
      msg: "Files have been updated."

# execution-order

Advanced Control & Summary

overriding defaults

Running a Handler Immediately

Normally, handlers wait until all tasks finish. If you need a handler to run immediately in the middle of a play, you can force Ansible to execute the queue early using meta: flush_handlers.

flush.ymlYAML

1 2 3 4 5 6 7 8 9 10 11

tasks:
  - name: Create file
    template:
      src: temp.j2
      dest: /tmp/file.txt
    notify: Show Message

  - meta: flush_handlers

  - name: Check file
    command: cat /tmp/file.txt

Important Points Summary

NOTIFY

Tells Ansible which specific handler should run if the task state changes.

TRIGGERS

Notification happens only if the task reports a changed state.

DEDUPLICATION

Multiple tasks can notify the same handler. Even if notified multiple times, the handler runs only once.

IDEMPOTENCY

Handlers prevent unnecessary actions (like unwanted service restarts), helping keep your playbooks incredibly efficient and idempotent.