>_cmd.script

useradd

Create a new user account

Users

By CMD Script Team · 4 min read · Last updated

SYNTAX
useradd [OPTIONS] USERNAME

Options

Command options and flags
FlagDescription
-mCreate the user's home directory if it doesn't already exist
-c COMMENTSet the GECOS field (typically the user's full name)
-s SHELLSet the user's login shell (e.g. /bin/bash)
-d HOME_DIRSpecify a custom home directory path instead of the default
-G GROUP1,GROUP2Add the user to one or more supplementary groups at creation time
-u UIDAssign a specific numeric user ID instead of the next available one
-e YYYY-MM-DDSet 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 user alice with a home directory
  • sudo useradd -m -s /bin/bash alice — also set the login shell to bash
  • sudo useradd -m -c "Alice Smith" alice — set the full-name comment field
  • sudo passwd alice — set a password immediately after creating the account (required, since useradd leaves 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 alice grants immediate group membership without a separate usermod call.
  • 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 -m and being surprised the user has no home directory (login may still work, but ~ resolves to a directory that doesn't exist).
  • Forgetting to run passwd afterward — a freshly useradd-ed account has no usable password and cannot log in interactively until one is set (or an SSH key is authorized).
  • Not setting -s and getting stuck with the distro's default shell (sometimes /bin/sh or even /usr/sbin/nologin on minimal systems), rather than /bin/bash.
  • Confusing useradd (low-level, no home dir/password by default) with adduser (Debian/Ubuntu's interactive wrapper), and expecting the same behavior from both.

Tips

  • Check /etc/default/useradd and /etc/login.defs to see what defaults (default shell, home directory skeleton, UID/GID ranges) apply on your system before assuming behavior.
  • Use -G at creation time to avoid a separate usermod -aG step when you already know which groups the account needs.
  • Pair useradd -m with /etc/skel customization 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 after useradd — 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/-G values in automation and configuration management (Ansible, Terraform, etc.) rather than relying on "next available" defaults, so UIDs stay consistent across servers.
  • Use -e to 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 useradd and adduser? useradd is 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 around useradd that prompts for details and creates a home directory by default.
  • Why would a newly created user be unable to log in? useradd doesn't set a password by default, so the account is locked until you run passwd USERNAME or 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 username creates 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.