1.. _intro_modules:
2
3Introduction to modules
4=======================
5
6Modules (also referred to as "task plugins" or "library plugins") are discrete units of code that can be used from the command line or in a playbook task. Ansible executes each module, usually on the remote managed node, and collects return values. In Ansible 2.10 and later, most modules are hosted in collections.
7
8You can execute modules from the command line::
9
10    ansible webservers -m service -a "name=httpd state=started"
11    ansible webservers -m ping
12    ansible webservers -m command -a "/sbin/reboot -t now"
13
14Each module supports taking arguments.  Nearly all modules take ``key=value`` arguments, space delimited.  Some modules take no arguments, and the command/shell modules simply take the string of the command you want to run.
15
16From playbooks, Ansible modules are executed in a very similar way::
17
18    - name: reboot the servers
19      command: /sbin/reboot -t now
20
21Another way to pass arguments to a module is using YAML syntax, also called 'complex args' ::
22
23    - name: restart webserver
24      service:
25        name: httpd
26        state: restarted
27
28All modules return JSON format data. This means modules can be written in any programming language. Modules should be idempotent, and should avoid making any changes if they detect that the current state matches the desired final state. When used in an Ansible playbook, modules can trigger 'change events' in the form of notifying :ref:`handlers <handlers>` to run additional tasks.
29
30You can access the documentation for each module from the command line with the ansible-doc tool::
31
32    ansible-doc yum
33
34For a list of all available modules, see the :ref:`Collection docs <list_of_collections>`, or run the following at a command prompt::
35
36    ansible-doc -l
37
38
39.. seealso::
40
41   :ref:`intro_adhoc`
42       Examples of using modules in /usr/bin/ansible
43   :ref:`working_with_playbooks`
44       Examples of using modules with /usr/bin/ansible-playbook
45   :ref:`developing_modules`
46       How to write your own modules
47   :ref:`developing_api`
48       Examples of using modules with the Python API
49   `Mailing List <https://groups.google.com/group/ansible-project>`_
50       Questions? Help? Ideas?  Stop by the list on Google Groups
51   `irc.libera.chat <https://libera.chat/>`_
52       #ansible IRC chat channel
53