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

Documentation

# win_user – Manages local Windows user accounts

- Synopsis

- Parameters

- See Also

- Examples

- Return Values

- Status

## Synopsis

- Manages local Windows user accounts.

- For non-Windows targets, use the user module instead.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
account_disabled boolean | Choices: no yes | `yes` will disable the user account. `no` will clear the disabled flag.
account_locked - | Choices: no | `no` will unlock the user account if locked.
description string |  | Description of the user.
fullname string |  | Full name of the user.
groups - |  | Adds or removes the user from this comma-separated list of groups, depending on the value of groups_action. When groups_action is `replace` and groups is set to the empty string ('groups='), the user is removed from all groups.
groups_action string | Choices: add replace ← remove | If `add`, the user is added to each group in groups where not already a member. If `replace`, the user is added as a member of each group in groups and removed from any other groups. If `remove`, the user is removed from each group in groups.
name string / required |  | Name of the user to create, remove or modify.
password string |  | Optionally set the user's password to this (plain text) value.
password_expired boolean | Choices: no yes | `yes` will require the user to change their password at next login. `no` will clear the expired password flag.
password_never_expires boolean | Choices: no yes | `yes` will set the password to never expire. `no` will allow the password to expire.
state string | Choices: absent present ← query | When `absent`, removes the user account if it exists. When `present`, creates or updates the user account. When `query` (new in 1.9), retrieves the user account details without making any changes.
update_password string | Choices: always ← on_create | `always` will update passwords if they differ. `on_create` will only set the password for newly created users.
user_cannot_change_password boolean | Choices: no yes | `yes` will prevent the user from changing their password. `no` will allow the user to change their password.

## See Also

See also

user – Manage user accounts

  The official documentation on the user module.

win_domain_membership – Manage domain/workgroup membership for a Windows host

  The official documentation on the win_domain_membership module.

win_domain_user – Manages Windows Active Directory user accounts

  The official documentation on the win_domain_user module.

win_group – Add and remove local groups

  The official documentation on the win_group module.

win_group_membership – Manage Windows local group membership

  The official documentation on the win_group_membership module.

win_user_profile – Manages the Windows user profiles

  The official documentation on the win_user_profile module.

## Examples

    - name: Ensure user bob is present
      win_user:
        name: bob
        password: B0bP4ssw0rd
        state: present
        groups:
          - Users

    - name: Ensure user bob is absent
      win_user:
        name: bob
        state: absent

## Return Values

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

Key | Returned | Description
--- | --- | ---
account_disabled boolean | user exists | Whether the user is disabled.
account_locked boolean | user exists | Whether the user is locked.
description string | user exists | The description set for the user. Sample: Username for test
fullname string | user exists | The full name set for the user. Sample: Test Username
groups list | user exists | A list of groups and their ADSI path the user is a member of. Sample: [{'name': 'Administrators', 'path': 'WinNT://WORKGROUP/USER-PC/Administrators'}]
name string | always | The name of the user Sample: username
password_expired boolean | user exists | Whether the password is expired.
password_never_expires boolean | user exists | Whether the password is set to never expire. Sample: True
path string | user exists | The ADSI path for the user. Sample: WinNT://WORKGROUP/USER-PC/username
sid string | user exists | The SID for the user. Sample: S-1-5-21-3322259488-2828151810-3939402796-1001
user_cannot_change_password boolean | user exists | Whether the user can change their own password.

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]

- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Paul Durivage (@angstwad)

- Chris Church (@cchurch)

Hint

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