New to Rust? Grab our free Rust for Beginners eBook Get it free →
useradd Command in Linux: Create and Configure a User
On Debian, adduser can prompt for a password, while useradd handles account creation through its options and system defaults. I couldn’t resist digging into how the two commands make “add a user” mean different things.
Separate the account-creation action from any policy a tool applies around it. See what useradd creates for a new local user.
What useradd creates
The shadow-utils useradd manual describes how the command creates a local account from the options you supply and system defaults.
A local account record ties a login name and UID to its primary group, home path and shell, while password data lives in the protected shadow database.
An account entry alone does not guarantee a home directory or a password that allows password-based login. Those choices depend on local configuration and the steps you run after creation.
| Command | Use it for |
|---|---|
| useradd | Low-level account creation with command-line options and system defaults. |
| adduser on Debian | A policy-layer interface that applies Debian account defaults and can prompt for a password. |
Check prerequisites and the local defaults
Use sudo or a root shell to write account records. A group named with the primary-group or supplementary-group option must already exist, or useradd rejects the account request.
Run useradd with its defaults option to see the settings this machine will use when you leave fields unspecified.
useradd -D
The Ubuntu 24.04 host used for this example printed HOME=/home and SHELL=/bin/sh. The command below chooses the shell explicitly and requests a home, while the base path still comes from local configuration.
Create an account with useradd
Choose the primary group and the supplementary groups before creating the account. The example uses a same-name primary group and an existing supplementary group.
Step 1. Create the supplementary group
Create webteam only when it is absent from the system group database. The groupadd manual describes how the system assigns its group ID when you do not choose one.
sudo groupadd webteam
Step 2. Create the account
The command below creates a home directory and a primary group named linus. It also selects the login shell and adds the account to webteam.
sudo useradd -m -U -s /bin/bash -G webteam linus
The -m option creates the home directory and copies files from the skeleton directory. The -U option requests a same-name primary group, while -G adds the existing supplementary group.
A successful useradd call may print nothing, so read the account record and home directory before treating the task as complete.
Step 3. Set a password when password login is required
Without an encrypted password value, useradd leaves the password field locked. Set a password separately with the system’s passwd utility, which prompts for the new value interactively.
sudo passwd linus
Do not pass a plaintext password through useradd’s password option, because local processes can read command-line arguments. Use the passwd manual for the interactive change.
Choose only the options the account needs
useradd flags change account fields or system defaults. Check the local manual when a less common option affects authentication policy.
Each account has one primary group and can have supplementary groups as well. Use -g to select the primary group and -G to name extra memberships for shared access.
| Option | Effect | Decision |
|---|---|---|
| -m | Create the home directory and copy skeleton files. | Use when the account needs a home directory. |
| -M | Do not create a home directory, even when CREATE_HOME is enabled. | Use only when another process manages the home. |
| -d PATH | Set the home-directory path in the account record. | Add -m to request directory creation instead of relying on local defaults. |
| -s SHELL | Set the login shell. | Name a shell installed on the system. |
| -U or -N | Create or suppress a same-name primary group. | Choose the group policy explicitly when defaults are unclear. |
| -g GROUP | Set the primary group. | The group must already exist. |
| -G GROUPS | Set supplementary groups at account creation. | Separate existing group names with commas. |
| -u UID | Assign a numeric user ID. | Leave it unset unless you must preserve a particular identity. |
| -r | Create a system account using the configured system ID range. | System accounts do not get a home unless you also request -m. |
| -e DATE and -f DAYS | Set account expiry and password inactivity after password expiry. | These options control different dates. |
| -p HASH | Supply an encrypted password value. | Other local processes may read that argument. Use passwd instead. |
| -D | Display or change the defaults for future useradd calls. | Changing a default affects later accounts on the machine. |
Home creation depends on the -m flag and the CREATE_HOME setting in /etc/login.defs. The -M flag suppresses home creation even when that setting is enabled.
Because -r selects the system ID range and skips home creation, add -m only when that account needs a directory.
Verify the account before handing it over
A zero exit status leaves the account’s actual fields unconfirmed, so read the account row and home directory first. Use id linus to check group membership.
getent passwd linus; id linus; test -d /home/linus && printf "home exists\n"
The account row shows the home path and shell, while id lists the primary and supplementary groups. The image uses an isolated Ubuntu account database, so its UID and GID values are fixture values rather than defaults for every system.
Fix the failures useradd reports
The useradd manual lists each exit code, and I reproduced the relevant failures in an isolated Ubuntu test root.
| Result | What it means | Next check |
|---|---|---|
| User or group name already in use, exit 9 | The requested login or group name is already present. | Look up the existing name. Use usermod when an existing user needs account changes. |
| Group does not exist, exit 6 | A name in -g or -G is missing. | Create the intended group or correct the name before retrying. |
| UID already in use, exit 4 | The requested numeric ID belongs to another account. | Leave -u unset unless an identity migration requires that exact number. |
| Cannot create home directory, exit 12 | The requested directory could not be created. | Check its parent path, mount, permissions, and security policy. Then read the account row before retrying. |
| No directory, logging in with HOME=/ | The account record names a home path, but the directory is absent. | Request home creation with -m, then check the parent path and verify the directory. |
In the isolated Ubuntu test root, a home-creation failure with exit 12 left the account row. Read the record before trying again.
Change an existing account with usermod
useradd creates a new account, while usermod changes an existing one, and only usermod accepts -a for appending supplementary groups.
| Goal | Command | Effect |
|---|---|---|
| Add one supplementary group | usermod -aG docker linus | Appends docker and preserves the other supplementary groups. |
| Replace supplementary groups | usermod -G webteam linus | Replaces the supplementary-group list with webteam. |
| Lock password authentication | passwd -l linus | Locks the password field. Other authentication methods may still allow access. |
sudo usermod -aG docker linus
The usermod manual defines -a as append and requires it with -G for that behavior. The userdel manual documents removal separately, including its home-directory removal option, so check backups and ownership before account removal.
Start a fresh login after changing groups
A process keeps its original supplementary groups until it ends, so open a fresh login session after changing membership and run id there.
id
In the isolated test root, starting a process with the updated group database made id report webteam and docker. Debian’s account manual notes that already-running processes keep their previous group list.
Frequently asked questions
A valid account row can still point to a directory that was never created.
Does useradd create a home directory by default?
That depends on the local CREATE_HOME setting. Use -m to request a home directory for a regular account, and use -M to suppress it. A system account created with -r also needs -m to receive a home.
Does useradd set a password?
Without an encrypted password value, useradd leaves the password field locked for password-based authentication. Set a password separately with the system’s passwd utility, and do not pass plaintext as a useradd command-line argument.
Can useradd add an existing user to a group?
No. Use usermod -aG group username to append membership without dropping the user’s other supplementary groups. The new membership applies to login sessions started after the change.
