sodcalculator

10 Tech How-To

How useradd Works in Linux: A Step-by-Step Guide

Guide 10-46233 · Updated · Step by step

This guide explains how the useradd command creates user accounts on Linux systems. You’ll learn the syntax, common options, and practical examples, plus how to avoid typical mistakes and troubleshoot issues. No prior knowledge beyond basic terminal usage is assumed.

What You’ll Need

  • A Linux system with a terminal (any distribution works).
  • Root or sudo access to run useradd (it requires superuser privileges).
  • Basic familiarity with the command line (navigating, running commands).

Step-by-Step

  1. Open a terminal and become root or use sudo. For example: sudo -i or prefix every command with sudo.
  2. Check the current options on your system: useradd -h or man useradd to see the exact flags supported. This guide covers the most common ones.
  3. Create a basic user with the simplest syntax: useradd username. This creates the user with default settings: no password (locked), home directory not created unless specified, and default shell (usually /bin/sh or /bin/bash).
  4. Set a password for the new user: passwd username. You’ll be prompted to enter and confirm the password. Until you do this, the account is locked.
  5. Create a home directory automatically by adding the -m flag: useradd -m username. This creates /home/username and copies skeleton files from /etc/skel (like .bashrc).
  6. Specify a custom home directory with -d: useradd -m -d /custom/path username. The -m flag tells it to create the directory if it doesn’t exist.
  7. Set the default shell with -s: useradd -m -s /bin/bash username. Use /bin/bash for a typical bash shell, or /usr/sbin/nologin for a system account that shouldn’t log in interactively.
  8. Add the user to supplementary groups with -G: useradd -m -G sudo,developers username. The sudo group gives admin privileges on many distros; replace with your actual group names.
  9. Set the primary group with -g: useradd -m -g developers username. If not specified, a new group with the same name as the user is created.
  10. Set an expiry date for the account using -e in YYYY-MM-DD format: useradd -m -e 2026-12-31 username. After this date, the user cannot log in.
  11. Create a system account (for services, not humans) with -r: useradd -r -s /usr/sbin/nologin myservice. This creates a user with a UID in the system range and no home directory by default.
  12. Verify the user was created by checking /etc/passwd (grep username) or using id username to see UID, GID, and groups.
  13. To delete a user (if needed), use userdel -r username (the -r removes the home directory and mail spool).

Common Mistakes

  • Forgetting to set a password – the account remains locked; you must run passwd username.
  • Not using -m – many beginners expect a home directory to be created automatically, but it isn’t unless you add the flag.
  • Using -g instead of -G – -g sets the primary group, while -G adds supplementary groups. Mixing them up can give the user unexpected permissions.
  • Specifying a group that doesn’t exist – useradd will fail with an error. Create the group first with groupadd.
  • Using a UID that’s already taken – if you use -u with a conflicting UID, the command fails. Let the system choose automatically unless you have a specific reason.
  • Creating system users without -r – this can assign a normal UID range, which may conflict with future regular users.

Tips

  • Use -m for human users – it’s almost always what you want for a real person.
  • Set the shell to /bin/bash for interactive users; many distros default to /bin/sh which is less user-friendly.
  • Add users to the sudo group (on Debian/Ubuntu) or wheel (on RHEL/CentOS) to grant admin rights – check your distro’s convention.
  • Use -k to specify a custom skeleton directory if you want different default files than /etc/skel.
  • Check the default values with useradd -D – it shows the defaults for group, home, shell, etc., which you can override per user.
  • For automation, use --create-home and --shell long options – they’re more readable in scripts.

Troubleshooting

  • “useradd: cannot lock /etc/passwd” – another process is modifying user files. Wait a moment or check for running package managers (like apt or yum) and let them finish.
  • “useradd: group ‘xyz’ does not exist” – you specified a group that isn’t defined. Run groupadd xyz first, or use an existing group name.
  • “useradd: user ‘name’ already exists” – the username is taken. Choose a different name or delete the old user with userdel if appropriate.
  • Home directory not created – you forgot -m. You can create it manually with mkdir /home/username and copy files from /etc/skel.
  • User can’t log in – check if the account is locked (password not set), the shell is valid (exists in /etc/shells), or the home directory has correct permissions (should be owned by the user).
  • UID/GID conflicts – if you see a warning about UID already in use, choose a different UID with -u or let the system pick automatically by not specifying one.

Frequently Asked Questions

Does useradd create a home directory by default?

No. On most Linux systems, useradd does not create a home directory unless you use the -m (or --create-home) option. Some distributions may have a default that creates it, but it’s safer to always include -m for human users.

What is the difference between useradd and adduser?

adduser is a friendly Perl script that calls useradd and then does extra steps like creating the home directory, setting a password, and copying skeleton files. useradd is the low-level binary that only performs the core task of adding the user entry.

How do I set a password non-interactively?

You can pipe the password to passwd using echo 'password' | passwd --stdin username (on RHEL/CentOS) or use the chpasswd command: echo 'username:password' | chpasswd. Be aware that this exposes the password in the shell history; use with caution.

Can I create a user without root access?

No. Creating a user modifies system files like /etc/passwd and /etc/shadow, which require root privileges. You must use sudo or switch to root.

What does the -r flag do exactly?

The -r flag creates a system account. It assigns a UID from the system range (usually 1-999) instead of the normal user range (usually 1000+). System accounts are typically used for daemons and services, and they often have no home directory or login shell.

How do I change a user’s shell after creation?

Use the chsh command as root: chsh -s /bin/bash username. This updates the shell field in /etc/passwd.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →