community.windows.win_user_profile – Manages the Windows user profiles.

Note

This plugin is part of the community.windows collection (version 1.7.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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

To use it in a playbook, specify: community.windows.win_user_profile.

Synopsis

  • Used to create or remove user profiles on a Windows host.
  • This can be used to create a profile before a user logs on or delete a profile when removing a user account.
  • A profile can be created for both a local or domain account.

Parameters

Parameter Choices/Defaults Comments
name
string
Specifies the base name for the profile path.
When state is present this is used to create the profile for username at a specific path within the profile directory.
This cannot be used to specify a path outside of the profile directory but rather it specifies a folder(s) within this directory.
If a profile for another user already exists at the same path, then a 3 digit incremental number is appended by Windows automatically.
When state is absent and username is not set, then the module will remove all profiles that point to the profile path derived by this value.
This is useful if the account no longer exists but the profile still remains.
remove_multiple
boolean
    Choices:
  • no ←
  • yes
When state is absent and the value for name matches multiple profiles the module will fail.
Set this value to yes to force the module to delete all the profiles found.
state
string
    Choices:
  • absent
  • present ←
Will ensure the profile exists when set to present.
When creating a profile the username option must be set to a valid account.
Will remove the profile(s) when set to absent.
When removing a profile either username must be set to a valid account, or name is set to the profile's base name.
username
sid
The account name of security identifier (SID) for the profile.
This must be set when state is present and must be a valid account or the SID of a valid account.
When state is absent then this must still be a valid account number but the SID can be a deleted user's SID.

See Also

See also

ansible.windows.win_user

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

community.windows.win_domain_user

The official documentation on the community.windows.win_domain_user module.

Examples

- name: Create a profile for an account
  community.windows.win_user_profile:
    username: ansible-account
    state: present

- name: Create a profile for an account at C:\Users\ansible
  community.windows.win_user_profile:
    username: ansible-account
    name: ansible
    state: present

- name: Remove a profile for a still valid account
  community.windows.win_user_profile:
    username: ansible-account
    state: absent

- name: Remove a profile for a deleted account
  community.windows.win_user_profile:
    name: ansible
    state: absent

- name: Remove a profile for a deleted account based on the SID
  community.windows.win_user_profile:
    username: S-1-5-21-3233007181-2234767541-1895602582-1305
    state: absent

- name: Remove multiple profiles that exist at the basename path
  community.windows.win_user_profile:
    name: ansible
    state: absent
    remove_multiple: yes

Return Values

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

Key Returned Description
path
string
always
The full path to the profile for the account. This will be null if state=absent and no profile was deleted.

Sample:
C:\Users\ansible


Authors

  • Jordan Borean (@jborean93)

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