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. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.env for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

Synopsis

  • Allows you to query the environment variables available on the controller when you invoked Ansible.

Terms

Parameter

Comments

Terms

string / required

Environment variable or list of them to lookup the values for.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.env', key1=value1, key2=value2, ...) and query('ansible.builtin.env', key1=value1, key2=value2, ...)

Parameter

Comments

default

any

added in ansible-core 2.13

What return when the variable is undefined

Default: ""

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('ansible.builtin.env', term1, term2, key1=value1, key2=value2) and query('ansible.builtin.env', term1, term2, key1=value1, key2=value2)
  • You can pass the Undefined object as default to force an undefined error

Examples

- name: Basic usage
  ansible.builtin.debug:
    msg: "'{{ lookup('ansible.builtin.env', 'HOME') }}' is the HOME environment variable."

- name: Before 2.13, how to set default value if the variable is not defined
  ansible.builtin.debug:
    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE') | default('World', True) }}"

- name: Example how to set default value if the variable is not defined
  ansible.builtin.debug:
    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE', default='World') }}"

- name: Fail if the variable is not defined by setting default value to 'Undefined'
  ansible.builtin.debug:
    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE', default=Undefined) }}"

- name: Fail if the variable is not defined by setting default value to 'undef()'
  ansible.builtin.debug:
    msg: "Hello {{ lookup('ansible.builtin.env', 'UNDEFINED_VARIABLE', default=undef()) }}"

Return Value

Key

Description

Return value

list / elements=string

Values from the environment variables.

Returned: success

Authors

  • Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/env_lookup.html