What are Handlers in Ansible? And how to use them with examples.

Card Puncher Data Processing


Handlers 1) are tasks that are:

  • defined globally outside a play
  • executed
    • at the end of the playbook.
    • only when the task has the changed status
    • only once (no matter how many times it was notified)
  • called by the notify property in case of state change during task execution.

They are mostly used to restart, reload, and test that services are up and running.


Playbook form

This example shows you a playbook.

If the file template.j2 has changed, the memcached and apache services will be restarted.

# handlers definition
  - name: restart memcached
      name: memcached
      state: restarted
    listen: "restart web services" # group handlers in one call
  - name: restart apache
      name: apache
      state: restarted
    listen: "restart web services" 

# Playbook
- hosts: webservers
  remote_user: root
  - name: template configuration file
      src: template.j2
      dest: /etc/foo.conf
    notify: # Call the handlers one by one
       - restart memcached
       - restart apache

    - name: restart everything
      command: echo "this task will restart the web services"
      notify: "restart web services" # Call the handlers in one call

Role form

This example shows you handlers in a role.

The handlers are generally in the roleName\handlers\main.yml file:

# a single
- name: 'prometheus reload'
  become: yes
    name: 'prometheus.service'
    enabled: 'yes'
    daemon_reload: yes
    state: restarted

# multiple, as of version 2.8, you need to use include_tasks (not block or import_tasks)
- name: 'prom-node-exporter restart'
  include_tasks: handlers/node_exporter_handlers.yml


  • Handler names and listen topics live in a global namespace.
  • If two handler tasks have the same name, only one will run.

You cannot notify a handler that is defined inside of an include. As of Ansible 2.1, this does work, however the include must be static.


  • The notify keyword add an handler to a set of handler (ie an handler is run only once by section)
  • The set is flushed (processed) by default at the end of a section
  • The executions occurs in the order defined in the handlers section (handlers are always run in the same order they are defined, not in the order listed in the notify-statement.)

Handlers notified within:

  • pre_tasks, tasks, and post_tasks sections are automatically flushed in the end of section where they were notified;
  • roles section are automatically flushed in the end of tasks section, but before any tasks handlers.

If you ever want to flush all the handler commands immediately you can do this:

   - shell: some tasks go here
   - meta: flush_handlers
   - shell: some other tasks

In the above example any queued up handlers would be processed early when the meta statement was reached.


Interactive authentication required

Unable to restart service postfix: Failed to restart postfix.service: Interactive authentication required.
See system logs and 'systemctl status postfix.service' for details.

Handler are run with the connected user privilege if you want to perform action that requires root privilege, you should become root.


- name: restart postfix
  service: name=postfix state=restarted
  become: true

How to resolve: The requested handler was not found

Possible resolution:

  • check the name of the handler or of your listen
  • if you use an include_tasks, check the path. If the file does not exist, Ansible may silently run.

Discover More
Card Puncher Data Processing
Ansible - Role

Roles is the reusable unit of Ansible. You may think of it as a function. It: helps make playbook content self-contained works well with things like git submodules for sharing content with others....
Card Puncher Data Processing
Ansible - Task Status

Article the task status A variable that is registered to give the result of the task would have the following structure. With changed_when and failed_when The error will not be counted as...
Card Puncher Data Processing
Ansible PlayBook - Task

A task is a call to an ansible module with arguments located in a play list. Variables can be used in arguments to modules. Tasks are executed top to bottom one at a time, against matched by the...

Share this page:
Follow us:
Task Runner