1.. _common_return_values:
2
3Return Values
4-------------
5
6.. contents:: Topics
7
8Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by
9the `ansible` program. Each module can optionally document its own unique return values (visible through ansible-doc and on the :ref:`main docsite<ansible_documentation>`).
10
11This document covers return values common to all modules.
12
13.. note:: Some of these keys might be set by Ansible itself once it processes the module's return information.
14
15
16Common
17^^^^^^
18
19backup_file
20```````````
21For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created.
22
23changed
24```````
25A boolean indicating if the task had to make changes.
26
27failed
28``````
29A boolean that indicates if the task was failed or not.
30
31invocation
32``````````
33Information on how the module was invoked.
34
35msg
36```
37A string with a generic message relayed to the user.
38
39rc
40``
41Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains 'return code' of these utilities.
42
43results
44```````
45If this key exists, it indicates that a loop was present for the task and that it contains a list of the normal module 'result' per item.
46
47skipped
48```````
49A boolean that indicates if the task was skipped or not
50
51stderr
52``````
53Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains the error output of these utilities.
54
55stderr_lines
56````````````
57When `stderr` is returned we also always provide this field which is a list of strings, one item per line from the original.
58
59stdout
60``````
61Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc). This field contains the normal output of these utilities.
62
63stdout_lines
64````````````
65When `stdout` is returned, Ansible always provides a list of strings, each containing one item per line from the original output.
66
67
68.. _internal_return_values:
69
70Internal use
71^^^^^^^^^^^^
72
73These keys can be added by modules but will be removed from registered variables; they are 'consumed' by Ansible itself.
74
75ansible_facts
76`````````````
77This key should contain a dictionary which will be appended to the facts assigned to the host. These will be directly accessible and don't require using a registered variable.
78
79exception
80`````````
81This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).
82
83warnings
84````````
85This key contains a list of strings that will be presented to the user.
86
87deprecations
88````````````
89This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are `msg` and `version`, values are string, value for the `version` key can be an empty string.
90
91.. seealso::
92
93   :ref:`all_modules`
94       Learn about available modules
95   `GitHub modules directory <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_
96       Browse source of core and extras modules
97   `Mailing List <https://groups.google.com/group/ansible-devel>`_
98       Development mailing list
99   `irc.libera.chat <https://libera.chat/>`_
100       #ansible IRC chat channel
101