W3cubDocs

/Ansible 2.10

ansible.windows.win_environment – Modify environment variables on windows hosts

Note

This plugin is part of the ansible.windows collection.

To install it use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_environment.

Synopsis

  • Uses .net Environment to set or remove environment variables and can set at User, Machine or Process level.
  • User level environment variables will be set, but not available until the user has logged off and on again.

Parameters

Parameter Choices/Defaults Comments
level
string / required
    Choices:
  • machine
  • process
  • user
The level at which to set the environment variable.
Use machine to set for all users.
Use user to set for the current user that ansible is connected as.
Use process to set for the current process. Probably not that useful.
name
string / required
The name of the environment variable.
state
string
    Choices:
  • absent
  • present ←
Set to present to ensure environment variable is set.
Set to absent to ensure it is removed.
value
string
The value to store in the environment variable.
Must be set when state=present and cannot be an empty string.
Can be omitted for state=absent.

Notes

Note

  • This module is best-suited for setting the entire value of an environment variable. For safe element-based management of path-like environment vars, use the ansible.windows.win_path module.
  • This module does not broadcast change events. This means that the minority of windows applications which can have their environment changed without restarting will not be notified and therefore will need restarting to pick up new environment settings. User level environment variables will require the user to log out and in again before they become available.

See Also

See also

ansible.windows.win_path

The official documentation on the ansible.windows.win_path module.

Examples

- name: Set an environment variable for all users
  ansible.windows.win_environment:
    state: present
    name: TestVariable
    value: Test value
    level: machine

- name: Remove an environment variable for the current user
  ansible.windows.win_environment:
    state: absent
    name: TestVariable
    level: user

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
before_value
string
always
the value of the environment key before a change, this is null if it didn't exist

Sample:
C:\Windows\System32
value
string
always
the value the environment key has been set to, this is null if removed

Sample:
C:\Program Files\jdk1.8


Authors

  • Jon Hawkesworth (@jhawkesworth)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/windows/win_environment_module.html