win_environment – Modify environment variables on windows hosts — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_environment – Modify environment variables on windows hosts

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## 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 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

win_path – Manage Windows path environment variables
  The official documentation on the win_path module.

## Examples

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

    - name: Remove an environment variable for the current user
      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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Jon Hawkesworth (@jhawkesworth)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.