win_environment - Modifies environment variables on windows hosts.

New in version 2.0.


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


parameter required default choices comments
yes no default
  • 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.
yes no default
The name of the environment variable
no present
  • present
  • absent
present to ensure environment variable is set, or absent to ensure it is removed
no no default
The value to store in the environment variable. Can be omitted for state=absent


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

- name: Remove an environment variable for the current user
    state: absent
    name: TestVariable
    level: user

Return Values

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

name description returned type sample
the value of the environment key before a change, this is null if it didn't exist
always string C:\Windows\System32
the name of the environment key the module checked
always string JAVA_HOME
the value the environment key has been set to
always string C:\Program Files\jdk1.8
the level set when calling the module
always string machine



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


This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2017 Michael DeHaan
© 2017 Red Hat, Inc.
Licensed under the GNU General Public License version 3.