Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Permissions and Users

Linux useradd command

Reference for the Linux useradd command: create users with a home directory, shell, groups and UID, set defaults with -D, and learn how it differs from adduser.

useradd creates a new account by adding entries to /etc/passwd, /etc/shadow and /etc/group (and optionally a home directory copied from /etc/skel). It is a low-level tool from the shadow-utils or shadow package: it does exactly what you tell it and nothing more. It does not set a password, so a new account is locked until you run passwd.

Defaults such as the base directory for home folders, the default shell and the UID range come from /etc/default/useradd and /etc/login.defs. Debian and Ubuntu also ship adduser, a friendlier Perl wrapper that prompts for a password and always makes a home directory; scripts should use useradd because it behaves the same on every distribution.

Terminal
sudo useradd -m -s /bin/bash alice

Try it

Creating accounts needs root, which the sandbox does not have. These examples use the read-only parts: the files useradd edits and the built-in defaults.

Bash Where accounts live

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Choosing the next free UID (sample data)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
useradd [OPTION]... LOGIN
useradd -D [OPTION]...
Option Description
-m, --create-home Create the home directory and copy files from the skeleton directory.
-M Do not create a home directory (even if the system default says to).
-d DIR Use DIR as the home directory.
-s SHELL Login shell, for example /bin/bash or /usr/sbin/nologin.
-u UID, -o Set the numeric ID; with -o allow a duplicate (not recommended).
-g GROUP Primary group (a name or GID that must exist).
-G LIST Comma-separated supplementary groups.
-N Do not create a group named like the user.
-r Create a system account (low UID, no home by default, no aging).
-c TEXT Comment (GECOS) field, usually the full name.
-e DATE, -f DAYS Account expiry date; days after password expiry until the account is disabled.
-k DIR Skeleton directory to copy (with -m).
-D Show or change the defaults instead of creating a user.

Returns: 0 on success. Common failures: 9 (name already in use), 4 (UID in use), 6 (group does not exist), 1 (cannot update the password file).

Usage notes

  • No password is set. The ! or * in /etc/shadow blocks password login. Run sudo passwd alice, or install an SSH key for key-based access.
  • -m is not always the default. Red Hat based systems create the home directory by default (CREATE_HOME yes); Debian does not. Always pass -m or -M explicitly in scripts.
  • A private group is created with the same name and GID as the user, unless you pass -g or -N. That enables the "user private group" scheme where files are group-writable only for the owner.
  • Service accounts should be created with -r -s /usr/sbin/nologin so nobody can log in as them.
  • Add to groups later with usermod -aG; with -G at creation time the list is exact.
  • Names: lowercase letters, digits, _ and -, up to 32 characters, and not starting with a digit or dash. Keep them portable.
  • Check the result with id alice and getent passwd alice.