# Return Values

<div class="contents">

Topics

</div>

Ansible modules normally return a data structure that can be registered into a variable, or seen directly when output by the <span class="title-ref">ansible</span> program. Each module can optionally document its own unique return values (visible through ansible-doc and on the `main docsite<ansible_documentation>`).

This document covers return values common to all modules.

> [!NOTE]
> Some of these keys might be set by Ansible itself once it processes the module's return information.

## Common

### backup_file

For those modules that implement <span class="title-ref">backup=no\|yes</span> when manipulating files, a path to the backup file created if original file was changed.

> ```
> "backup_file": "./foo.txt.32729.2020-07-30@06:24:19~"
> ```

### changed

A boolean indicating if the task had to make changes to the target or delegated host.

> ```
> "changed": true
> ```

### diff

Information on differences between the previous and current state. Often a dictionary with entries `before` and `after`, which will then be formatted by the callback plugin to a diff view.

> ```
> "diff": [
>         {
>             "after": "",
>             "after_header": "foo.txt (content)",
>             "before": "",
>             "before_header": "foo.txt (content)"
>         },
>         {
>             "after_header": "foo.txt (file attributes)",
>             "before_header": "foo.txt (file attributes)"
>         }
> ```

### failed

A boolean that indicates if the task was failed or not.

> ```
> "failed": false
> ```

### invocation

Information on how the module was invoked.

> ```
> "invocation": {
>         "module_args": {
>             "_original_basename": "foo.txt",
>             "attributes": null,
>             "backup": true,
>             "checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
>             "content": null,
>             "delimiter": null,
>             "dest": "./foo.txt",
>             "directory_mode": null,
>             "follow": false,
>             "force": true,
>             "group": null,
>             "local_follow": null,
>             "mode": "666",
>             "owner": null,
>             "regexp": null,
>             "remote_src": null,
>             "selevel": null,
>             "serole": null,
>             "setype": null,
>             "seuser": null,
>             "src": "/Users/foo/.ansible/tmp/ansible-tmp-1596115458.110205-105717464505158/source",
>             "unsafe_writes": null,
>             "validate": null
>         }
> ```

### msg

A string with a generic message relayed to the user.

> ```
> "msg": "line added"
> ```

### rc

Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains 'return code' of these utilities.

> ```
> "rc": 257
> ```

### results

If 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.

> ```
> "results": [
>     {
>         "ansible_loop_var": "item",
>         "backup": "foo.txt.83170.2020-07-30@07:03:05~",
>         "changed": true,
>         "diff": [
>             {
>                 "after": "",
>                 "after_header": "foo.txt (content)",
>                 "before": "",
>                 "before_header": "foo.txt (content)"
>             },
>             {
>                 "after_header": "foo.txt (file attributes)",
>                 "before_header": "foo.txt (file attributes)"
>             }
>         ],
>         "failed": false,
>         "invocation": {
>             "module_args": {
>                 "attributes": null,
>                 "backrefs": false,
>                 "backup": true
>             }
>         },
>         "item": "foo",
>         "msg": "line added"
>     },
>     {
>         "ansible_loop_var": "item", 
>         "backup": "foo.txt.83187.2020-07-30@07:03:05~",
>         "changed": true,
>         "diff": [
>             {
>                 "after": "",
>                 "after_header": "foo.txt (content)",
>                 "before": "",
>                 "before_header": "foo.txt (content)"
>             },
>             {
>                 "after_header": "foo.txt (file attributes)",
>                 "before_header": "foo.txt (file attributes)"
>             }
>         ],
>         "failed": false,
>         "invocation": {
>             "module_args": {
>                 "attributes": null,
>                 "backrefs": false,
>                 "backup": true
>             }
>         },
>         "item": "bar",
>         "msg": "line added"
>     }
>     ]
> ```

### skipped

A boolean that indicates if the task was skipped or not

> ```
> "skipped": true
> ```

### stderr

Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities.

> ```
> "stderr": "ls: foo: No such file or directory"
> ```

### stderr_lines

When <span class="title-ref">stderr</span> is returned we also always provide this field which is a list of strings, one item per line from the original.

> ```
> "stderr_lines": [
>         "ls: doesntexist: No such file or directory"
>         ]
> ```

### stdout

Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities.

> ```
> "stdout": "foo!"
> ```

### stdout_lines

When <span class="title-ref">stdout</span> is returned, Ansible always provides a list of strings, each containing one item per line from the original output.

> ```
> "stdout_lines": [
> "foo!"
> ]
> ```

## Internal use

These keys can be added by modules but will be removed from registered variables; they are 'consumed' by Ansible itself.

### ansible_facts

This 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.

### exception

This key can contain traceback information caused by an exception in a module. It will only be displayed on high verbosity (-vvv).

### warnings

This key contains a list of strings that will be presented to the user.

### deprecations

This key contains a list of dictionaries that will be presented to the user. Keys of the dictionaries are <span class="title-ref">msg</span> and <span class="title-ref">version</span>, values are string, value for the <span class="title-ref">version</span> key can be an empty string.

<div class="seealso">

`list_of_collections`  
Browse existing collections, modules, and plugins

[GitHub modules directory](https://github.com/ansible/ansible/tree/devel/lib/ansible/modules)  
Browse source of core and extras modules

`Communication<communication>`  
Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide

</div>