For Linux and other POSIX hosts, create accounts with ansible.builtin.user and provide a password hash—not a cleartext password. Store the hash in an encrypted variable source such as Ansible Vault. For local Windows accounts, use ansible.windows.win_user; macOS has different password handling and should not use a Linux hash example unchanged.
Create a user on Linux or another POSIX system
The built-in ansible.builtin.user module manages POSIX accounts. Specify the account name and desired state, then add only the attributes your account policy requires. The example below creates a home directory and adds the account to the listed supplementary group while preserving other supplementary memberships:
- name: Ensure a local POSIX account exists
ansible.builtin.user:
name: deploy
state: present
password: "{{ deploy_password_hash }}"
groups:
- deploy
append: true
create_home: truedeploy_password_hash is a placeholder for a previously generated hash stored in an encrypted variable source; it is not a password to paste into the playbook. You can also define attributes such as a shell, UID, or home directory when they are part of the intended account configuration. See the ansible.builtin.user module reference for parameters and platform behavior.
Choose group behavior deliberately
When you specify groups, the module’s behavior can affect memberships beyond the groups listed. Set append: true if the listed groups should be added without removing other supplementary memberships. If you intend to make the supplied list authoritative, use the replacement behavior deliberately instead. Current module documentation says append is required when groups is specified starting in Ansible 2.21, so check the installed ansible-core version and satisfy its parameter requirements.
#1 Best Overall
How to add a password safely
On Linux and other POSIX systems, the module’s password parameter takes a hashed or encrypted password string. It does not turn a cleartext password into a hash for you. On Linux, that value is written to the target’s shadow database without validation; a malformed value can prevent password authentication, while special locked values may be intentional on some systems.
Generate a compatible hash
Ansible’s FAQ documents the password_hash filter as one way to derive a hash, and also gives examples using mkpasswd --method=sha-512 and openssl passwd -6 -noverify. These are examples, not a universal algorithm recommendation: confirm that the target operating system and the relevant Python or library support the chosen method. See Ansible’s guidance on hashing data and its FAQ on generating encrypted passwords for the user module.
Rank #2
Keep credentials out of playbook text
Do not put a cleartext password in a playbook or host_vars. Ansible’s FAQ recommends encrypting sensitive variables and files with Ansible Vault. Keep the hash in that protected variable source and reference it in the task, as in the example above. A hash is still sensitive account data and should not be treated as public configuration.
Decide whether Ansible should keep changing the password
The update_password option defines the password lifecycle when Ansible runs again. The module reference lists always as the default.
Rank #3
| Setting | Effect | Use when |
|---|---|---|
always |
Update the password when the supplied value differs from the account’s current value. | The managed value should continue to be reconciled on later runs. |
on_create |
Set the password only when creating the account. | Existing account passwords should not be reset by subsequent runs. |
Choose according to how you manage credentials and account changes; neither policy is right for every environment. The option and its default are documented in the module reference.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Account creation differs by target operating system
| Target | Module or behavior | Password consideration |
|---|---|---|
| Linux and other POSIX systems | ansible.builtin.user |
Supply a hash or encrypted value, not cleartext. |
| macOS | ansible.builtin.user, with platform-specific behavior |
The module documentation says the password is cleartext on macOS; password-setting behavior differs, including reporting changed whenever a password is passed. Do not reuse the Linux hash example unchanged. |
| Windows local accounts | ansible.windows.win_user |
Use the Windows module and its own parameters rather than the POSIX module. |
| Windows domain accounts | A domain-specific module and authentication setup | The local-account win_user workflow is not a substitute; confirm the module and collection version for your environment. |
For Windows local users, see the win_user module reference and the Ansible Windows usage guide. The connection and privilege escalation you configure must also permit account changes on the managed host; the appropriate setup depends on the operating system and execution policy.
Quick Recap
Common mistakes to avoid
- Passing cleartext to a POSIX task: the Linux/Unix password parameter expects a hash; Ansible does not hash it automatically.
- Assuming groups are always additive: decide whether to preserve other supplementary memberships and configure
appendaccordingly. - Using one password example on every platform: macOS and Windows do not share Linux password semantics.
- Resetting passwords unintentionally: select
update_passwordbased on whether later runs should reconcile changed values. - Using an incompatible hash method: check target OS support and relevant Ansible/Python dependencies before relying on a generation method.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
