+

Search Tips   |   Advanced Search

Adding modules and plugins locally

The easiest, quickest, and the most popular way to extend Ansible is to use a local module or a plugin. You can create them or copy existing ones for local use. You can store a local module or plugin on your Ansible control node and share it with your team or organization. You can also share a local plugin or module by including it in a collection or embedding it in a role, then publishing the collection or role on Ansible Galaxy. If you are using roles on Ansible Galaxy, then you are already using local modules and plugins without realizing it.

If you are using an existing module or plugin but Ansible can't find it, this page is all you need. However, if you want to create a plugin or a module, go to Developing plugins and Ansible module development: getting started topics and then return to this page to know how to add it locally.

Extending Ansible with local modules and plugins offers lots of shortcuts such as:

To save a local module or plugin such that Ansible can find and use it, add the module or plugin in the appropriate directory (the directories are specified in later parts of this topic).


Modules and plugins: what is the difference?

If you are looking to add local functionality to Ansible, you might wonder whether you need a module or a plugin. Here is a quick overview to help you decide between the two:


Adding a module locally

Ansible automatically loads all executable files found in certain directories as modules.

For local modules, use the name of the file as the module name: for example, if the module file is ~/.ansible/plugins/modules/local_users.py, use local_users as the module name.

To load your local modules automatically and make them available to all playbooks and roles, add them in any of these locations:

After you save your module file in one of these locations, Ansible loads it and you can use it in any local task, playbook, or role.

To confirm that my_custom_module is available:

or

Currently, the ansible-doc command can parse module documentation only from modules written in Python. If you have a module written in a programming language other than Python, please write the documentation in a Python file adjacent to the module file.

You can limit the availability of your local module. To use a local module only with selected playbooks or only with a single role, load it in one of the following locations:


Adding a plugin locally

Ansible loads plugins automatically too, and loads each type of plugin separately from a directory named for the type of plugin. Here's the full list of plugin directory names:

  • action_plugins*

  • cache_plugins

  • callback_plugins

  • connection_plugins

  • filter_plugins*

  • inventory_plugins

  • lookup_plugins

  • shell_plugins

  • strategy_plugins

  • test_plugins*

  • vars_plugins

After you add the plugins and verify that they are available for use, you can see the documentation for all the plugins except for the ones marked with an asterisk (*) above.

To load your local plugins automatically, add them in any of these locations:

After your plugin file is in one of these locations, Ansible loads it and you can use it in any local module, task, playbook, or role. Alternatively, you can edit your ansible.cfg file to add directories that contain local plugins. For details about adding directories of local plugins, see Ansible Configuration Settings.

To confirm that plugins/plugin_type/my_custom_plugin is available:

You can limit the availability of your local plugin. To use a local plugin only with selected playbooks or only with a single role, load it in one of the following locations:

Next Previous