useradd
Create a new user account
By CMD Script Team · 4 min read · Last updated
useradd [OPTIONS] USERNAMEOptions
| Flag | Description |
|---|---|
-m | Create the user's home directory if it doesn't already exist |
-c COMMENT | Set the GECOS field (typically the user's full name) |
-s SHELL | Set the user's login shell (e.g. /bin/bash) |
-d HOME_DIR | Specify a custom home directory path instead of the default |
-G GROUP1,GROUP2 | Add the user to one or more supplementary groups at creation time |
-u UID | Assign a specific numeric user ID instead of the next available one |
-e YYYY-MM-DD | Set an account expiration date |
Distribution compatibility
- Ubuntu
- Debian
- Fedora
- Arch
- macOS (not available; use dscl or System Settings instead)
What it does
useradd creates a new user account on the system by adding entries to /etc/passwd,
/etc/shadow, and /etc/group. On its own it's a fairly low-level tool: it doesn't set a
password or necessarily create a home directory unless told to — most of that behavior
is controlled by flags or by defaults in /etc/login.defs and /etc/default/useradd.
Beginner examples
sudo useradd -m alice— create useralicewith a home directorysudo useradd -m -s /bin/bash alice— also set the login shell to bashsudo useradd -m -c "Alice Smith" alice— set the full-name comment fieldsudo passwd alice— set a password immediately after creating the account (required, sinceuseraddleaves the account locked otherwise)
sudo useradd -m -s /bin/bash -c "Alice Smith" alice
Advanced examples
- Add the user to supplementary groups at creation time:
sudo useradd -m -G sudo,docker alicegrants immediate group membership without a separateusermodcall. - Assign an explicit UID for consistency across machines (e.g. matching NFS or container
UID mappings):
sudo useradd -m -u 1500 alice. - Set an account expiration date for temporary/contractor accounts:
sudo useradd -m -e 2026-12-31 contractor. - Use a custom home directory location:
sudo useradd -m -d /srv/app-users/alice alice.
sudo useradd -m -u 1500 -G docker -s /bin/bash -e 2026-12-31 contractor
Common mistakes
- Forgetting
-mand being surprised the user has no home directory (login may still work, but~resolves to a directory that doesn't exist). - Forgetting to run
passwdafterward — a freshlyuseradd-ed account has no usable password and cannot log in interactively until one is set (or an SSH key is authorized). - Not setting
-sand getting stuck with the distro's default shell (sometimes/bin/shor even/usr/sbin/nologinon minimal systems), rather than/bin/bash. - Confusing
useradd(low-level, no home dir/password by default) withadduser(Debian/Ubuntu's interactive wrapper), and expecting the same behavior from both.
Tips
- Check
/etc/default/useraddand/etc/login.defsto see what defaults (default shell, home directory skeleton, UID/GID ranges) apply on your system before assuming behavior. - Use
-Gat creation time to avoid a separateusermod -aGstep when you already know which groups the account needs. - Pair
useradd -mwith/etc/skelcustomization if you want new home directories to come pre-populated with default dotfiles or config.
Best practices
- Always run
passwd(or configure SSH key-based auth) right afteruseradd— an account with no password and no key is either unusable or, worse, misconfigured to allow blank-password login depending on PAM settings. - Prefer explicit
-u/-Gvalues in automation and configuration management (Ansible, Terraform, etc.) rather than relying on "next available" defaults, so UIDs stay consistent across servers. - Use
-eto set expiration dates on temporary or contractor accounts instead of relying on manual cleanup later.
Try it yourself
A simulated shell with a sample home directory — experiment freely, nothing leaves your browser. Type help to list supported commands.
Real-world use cases
- Provisioning a new team member's Linux account on a shared development server with the right shell, home directory, and group memberships in one command.
- Creating service-like human accounts with a fixed UID that must match across multiple servers for NFS-mounted home directories.
- Automating account creation in a shell script or configuration management playbook as part of onboarding.
Common interview questions
- What's the difference between
useraddandadduser?useraddis the low-level binary present on all Linux distros with minimal defaults (no home dir or password unless specified);adduser(Debian/Ubuntu) is a friendlier interactive wrapper arounduseraddthat prompts for details and creates a home directory by default. - Why would a newly created user be unable to log in?
useradddoesn't set a password by default, so the account is locked until you runpasswd USERNAMEor install an SSH key for that user. - How do you create a user and add them to existing groups in one step?
sudo useradd -m -G group1,group2 usernamecreates the account and adds it to the listed supplementary groups immediately.
Frequently Asked Questions
Why doesn't the new user have a home directory?
By default, useradd on some distros (notably Debian/Ubuntu) does not create a home directory unless you pass -m. Fedora/RHEL typically create one by default via useradd's configured defaults. Always check with -m to be safe.
Do I need root privileges to run useradd?
Yes. useradd modifies /etc/passwd, /etc/shadow, and /etc/group, which are only writable by root, so you must run it with sudo or as root.
What's the difference between useradd and adduser?
useradd is the low-level utility present on virtually all Linux distros; adduser (on Debian/Ubuntu) is a friendlier interactive Perl wrapper around useradd that prompts for a password, full name, and creates the home directory by default.
How do I set the new user's password?
useradd itself doesn't prompt for a password; run passwd USERNAME immediately afterward to set one, otherwise the account is created locked with no valid password.
Cheat sheet
Download a quick-reference cheat sheet for useradd.