ansible.builtin.env lookup – Read the value of environment variables
Note
This lookup plugin is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
plugin name
env
even without specifying the collections:
keyword.
However, we recommend you use the FQCN for easy linking to the
plugin documentation and to avoid conflicting with other collections that may have
the same lookup plugin name.
New in version 0.9: of ansible.builtin
Synopsis
Allows you to query the environment variables available on the controller when you invoked Ansible.
Parameters
Parameter |
Comments |
---|---|
Environment variable or list of them to lookup the values for. |
Notes
Note
The module returns an empty string if the environment variable is not defined. This makes it impossible to differentiate between the case the variable is not defined and the case the variable is defined but it contains an empty string.
The
default
filter requires second parameter to be set toTrue
in order to set a default value in the case the variable is not defined (see examples).
Examples
- name: Basic usage
debug:
msg: "'{{ lookup('env', 'HOME') }}' is the HOME environment variable."
- name: Example how to set default value if the variable is not defined
debug:
msg: "'{{ lookup('env', 'USR') | default('nobody', True) }}' is the user."
Return Values
Common return values are documented here, the following are the fields unique to this lookup:
Key |
Description |
---|---|
Values from the environment variables. Returned: success |
Authors
Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>
Hint
Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.