The easiest, quickest, and most popular way to extend Ansible is to copy or write a module or a plugin for local use. You can store local modules and plugins on your Ansible control node for use within your team or organization. You can also share a local plugin or module by embedding it in a role and publishing it on Ansible Galaxy. If you’ve been using roles off Galaxy, you may have been using local modules and plugins without even realizing it. If you’re using a local module or plugin that already exists, this page is all you need.
Extending Ansible with local modules and plugins offers lots of shortcuts:
To save a local module or plugin so Ansible can find and use it, drop the module or plugin in the correct “magic” directory. For local modules, use the name of the file as the module name: for example, if the module file is
local_users as the module name.
If you’re looking to add local functionality to Ansible, you may be wondering whether you need a module or a plugin. Here’s a quick overview of the differences:
Ansible automatically loads all executable files found in certain directories as modules, so you can create or add a local module in any of these locations:
ANSIBLE_LIBRARYenvironment variable (
$ANSIBLE_LIBRARYtakes a colon-separated list like
Once you save your module file in one of these locations, Ansible will load it and you can use it in any local task, playbook, or role.
To confirm that
my_custom_module is available:
ansible-doc -t module my_custom_module. You should see the documentation for that module.
To use a local module only in certain playbooks:
libraryin the directory that contains the playbook(s)
To use a local module only in a single role:
librarywithin that role
Ansible loads plugins automatically too, loading each type of plugin separately from a directory named for the type of plugin. Here’s the full list of plugin directory names:
You can create or add a local plugin in any of these locations:
ANSIBLE_plugin_type_PLUGINSenvironment variable (these variables, such as
$ANSIBLE_VARS_PLUGINStake colon-separated lists like
~/.ansible/plugins/- for example,
/usr/share/ansible/plugins/- for example,
Once your plugin file is in one of these locations, Ansible will load it and you can use it in a any local module, task, playbook, or role.
To confirm that
plugins/plugin_type/my_custom_plugin is available:
ansible-doc -t <plugin_type> my_custom_lookup_plugin. For example,
ansible-doc -t lookup my_custom_lookup_plugin. You should see the documentation for that plugin. This works for all plugin types except the ones marked with
*in the list above - see ansible-doc for more details.
To use your local plugin only in certain playbooks:
inventory_plugins) in the directory that contains the playbook(s)
To use your local plugin only in a single role:
strategy_plugins) within that role
When shipped as part of a role, the plugin will be available as soon as the role is called in the play.