Linux Labs
Where to start First steps track · 15 stages
Linux Labs
EN

useradd — create a user

6 min Ubuntu 24.04 · shadow 4.13

The useradd command creates a user account with a home directory, shell, groups and UID; passwd sets the password.

Cheat sheet

10 commands Printable version
  • sudo useradd -m -s /bin/bash alice with a home directory and bash
  • sudo passwd alice the password — a separate step
  • sudo useradd -m -s /bin/bash -G sudo bob straight into sudo group
  • sudo useradd -m -c 'Alice Smith' alice with a full name
  • sudo useradd -m -u 1500 carol with a given UID
  • sudo useradd -m -e 2026-12-31 intern the account expires that day
  • sudo useradd -r -s /usr/sbin/nologin -M app a system user
  • id alice check the result
  • useradd -D the defaults
  • sudo adduser dave interactive (Debian/Ubuntu)

Overview

useradd adds an entry to /etc/passwd, /etc/shadow and /etc/group. It runs only as root, so almost always through sudo.

A bare useradd name on Ubuntu has surprising defaults: no home directory is created, the shell is /bin/sh, there's no password, and password login is impossible. That's why -m and -s /bin/bash are written almost every time:

text 
student@ubuntu:~$ sudo useradd -m -s /bin/bash -c 'Alice Smith' alice
student@ubuntu:~$ getent passwd alice
alice:x:1001:1001:Alice Smith:/home/alice:/bin/bash
student@ubuntu:~$ id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice)

The passwd line's fields: name, x (the password lives in /etc/shadow), UID, primary group GID, comment, home directory, shell. useradd creates a group with the same name by itself. Regular users' UIDs start at 1000.

adduser is a Debian and Ubuntu wrapper: it asks for a password and a name, creates the home directory and sets bash. It's handy by hand; in scripts useradd with explicit options is more reliable.

Options

11

Defaults live in /etc/default/useradd and /etc/login.defs; see them with useradd -D. Full list — man useradd.

Option What it does Example
-m --create-home Create the home directory and copy /etc/skel into it. sudo useradd -m alice
-s --shell shell Login shell; without it Ubuntu uses /bin/sh. sudo useradd -m -s /bin/bash alice
-G --groups groups Supplementary groups, comma-separated — they must already exist. sudo useradd -m -G sudo,docker bob
-c --comment text A comment — usually the full name. sudo useradd -m -c 'Alice Smith' alice
-u --uid UID Set the UID by hand. sudo useradd -m -u 1500 carol
-r --system A system account — UID below 1000, no home directory by default. sudo useradd -r -s /usr/sbin/nologin app
-g --gid group A primary group instead of a new group named after the user. sudo useradd -m -g devs carol
-d --home-dir dir A home directory path instead of /home/name. sudo useradd -r -d /var/lib/app -M app
-M --no-create-home Don't create the home directory. sudo useradd -r -M app
-e --expiredate YYYY-MM-DD The date after which the account stops working. sudo useradd -m -e 2026-12-31 intern
-D --defaults Print or change the default settings. useradd -D

Nothing found. Try a shorter query.

Recipes

4

A user who can administer the machine

bash 
sudo useradd -m -s /bin/bash -G sudo bob
sudo passwd bob

On Ubuntu the sudo group grants running commands as root. For an existing user — sudo usermod -aG sudo bob (more in users-groups).

A system account for a service

bash 
sudo useradd -r -s /usr/sbin/nologin -d /var/lib/app -M app

-r picks a UID below 1000, -M skips the home directory, nologin blocks interactive login. A service runs as such a user via its unit (User=app).

A user with an SSH key instead of a password

bash 
sudo useradd -m -s /bin/bash deploy
sudo install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
echo 'ssh-ed25519 AAAA... deploy@laptop' | \
  sudo tee /home/deploy/.ssh/authorized_keys
sudo chown deploy:deploy /home/deploy/.ssh/authorized_keys
sudo chmod 600 /home/deploy/.ssh/authorized_keys

No password is set, so password login is closed while key login works — see ssh-keys.

What ends up in the new home directory

With -m the contents of /etc/skel are copied in: .bashrc, .profile, .bash_logout. Put files that every new user should get there.

Troubleshooting

6

useradd: Permission denied / cannot lock /etc/passwd

The command ran without root. Repeat it with sudo useradd ….

useradd: user 'alice' already exists

The name is taken. Check getent passwd alice. To change an existing user use usermod, to delete — userdel (see users-groups).

useradd: group 'devs' does not exist

A group in -G or -g must exist beforehand: sudo groupadd devs, then run useradd again.

The user exists but can't log in

No password is set — run sudo passwd alice. Check the password state with sudo passwd -S alice (L — locked, P — set) — see passwd.

A strange shell instead of bash: no history or completion

The user was created without -s and got /bin/sh. Change the shell: sudo usermod -s /bin/bash alice.

Could not chdir to home directory on login

The user was created without -m, so there's no home directory. Create one with the right owner: sudo mkhomedir_helper alice or sudo install -d -m 750 -o alice -g alice /home/alice.

Danger zone

1

Reusing a UID

If the machine once had a user with the same UID who left files behind, the new user becomes their owner. Before useradd -u, check that the UID is free and that no files on disk carry it: sudo find / -xdev -uid 1500.

See also

  • users-groups — change or delete a user, manage groups.
  • passwd — set or lock a password.
  • sudo — give a new user administrator rights.
  • chage — password and account expiry.
  • nologin — an account with no interactive login.
  • whoami — which account the current session runs as.

Found an inaccuracy? Report an error in the article

Lessons on this topic

Topics
Loading…