The useradd command is one of the most fundamental tools for user management in Linux systems. It allows system administrators to create new user accounts, configure user properties, and set up the user environment. This guide provides a comprehensive overview of the useradd command, covering everything from basic usage to advanced configuration options.

What is useradd?

useradd is a low-level utility for adding new user accounts to a Linux system. It is the primary command-line tool used to:

• Create new user accounts
• Set user properties (UID, GID, home directory, shell, etc.)
• Configure default user settings
• Set up user environment

Key Characteristics

• Low-level command: useradd creates the account but doesn’t set a password (use passwd for that)
• System-wide changes: Requires root/administrator privileges
• Configurable defaults: Uses /etc/default/useradd for default settings
• Minimal by default: Creates user with minimal configuration unless options are specified

Basic Syntax

useradd [OPTIONS] USERNAME

Requirements

• Root privileges: Must run with sudo or as root user
• Unique username: Username must not already exist
• Valid username format: Typically lowercase letters, numbers, hyphens, and underscores

Creating Your First User

Simple User Creation

The most basic command creates a user with default settings:

sudo useradd john

What happens:

• Creates user account “john”
• Assigns next available UID (User ID)
• Assigns default GID (Group ID)
• Creates home directory (if default config allows)
• Sets default shell (usually /bin/bash or /bin/sh)

Verify User Creation

Check if the user was created successfully:

# Check user information
id john

# View user details
getent passwd john

# Check if user exists
grep john /etc/passwd

Common Options and Flags

Essential Options

-m or --create-home

Creates the user’s home directory if it doesn’t exist.

sudo useradd -m john

Without -m:

• User account is created
• Home directory is NOT created
• User must use / or temporary directories

With -m:

• Home directory created at /home/john
• Copies skeleton files from /etc/skel
• Sets proper permissions

-d or --home-dir

Specifies a custom home directory path.

sudo useradd -m -d /home/johnsmith john

Example:

sudo useradd -m -d /var/www/john john
# Creates user with home directory at /var/www/john

-s or --shell

Sets the user’s default login shell.

sudo useradd -m -s /bin/bash john

Common shells:

• /bin/bash – Bash shell (most common)
• /bin/sh – POSIX shell
• /bin/zsh – Z shell
• /bin/fish – Fish shell
• /usr/sbin/nologin – Prevents login (for system accounts)
• /bin/false – Prevents login (for system accounts)

Example:

# Create user with zsh shell
sudo useradd -m -s /bin/zsh john

# Create system account that cannot login
sudo useradd -r -s /usr/sbin/nologin myservice

-u or --uid

Specifies a custom User ID (UID).

sudo useradd -m -u 1001 john

UID ranges:

• 0: Root user
• 1-999: System accounts
• 1000-65534: Regular users
• 65535: Usually reserved

Example:

# Create user with specific UID
sudo useradd -m -u 1500 john

# Check UID
id -u john  # Output: 1500

-g or --gid

Sets the primary group ID (GID) or group name.

# Using GID number
sudo useradd -m -g 1000 john

# Using group name
sudo useradd -m -g developers john

Important:

• Group must exist before assigning
• If not specified, creates a new group with same name as username

Example:

# First create the group
sudo groupadd developers

# Then create user with that group
sudo useradd -m -g developers john

-G or --groups

Adds user to additional supplementary groups.

sudo useradd -m -G sudo,developers,www-data john

Example:

# Create user in multiple groups
sudo useradd -m -G docker,sudo,developers john

# Verify groups
groups john
# Output: john : john sudo docker developers

-c or --comment

Sets the user’s full name or comment (GECOS field).

sudo useradd -m -c "John Smith" john

Example:

sudo useradd -m -c "John Smith - Developer" john

# View comment
getent passwd john | cut -d: -f5
# Output: John Smith - Developer

-e or --expiredate

Sets account expiration date.

sudo useradd -m -e 2024-12-31 john

Date formats:

• YYYY-MM-DD (e.g., 2024-12-31)
• YYYY/MM/DD
• Days since epoch

Example:

# Account expires on December 31, 2024
sudo useradd -m -e 2024-12-31 john

# Check expiration
chage -l john | grep "Account expires"

-f or --inactive

Sets the number of days after password expiration before account is disabled.

sudo useradd -m -f 30 john

Values:

• 0: Account disabled immediately after password expires
• -1: No expiration (default)
• N: Account disabled N days after password expiration

-k or --skel

Specifies skeleton directory (files to copy to home directory).

sudo useradd -m -k /etc/custom-skel john

Default: /etc/skel

Example:

# Create custom skeleton directory
sudo mkdir -p /etc/custom-skel
sudo cp .bashrc .vimrc /etc/custom-skel/

# Create user with custom skeleton
sudo useradd -m -k /etc/custom-skel john

-r or --system

Creates a system account (UID < 1000, no home directory by default).

sudo useradd -r myservice

System account characteristics:

• UID typically < 1000
• No home directory (unless -m is specified)
• Usually has /usr/sbin/nologin shell
• Used for services and daemons

Example:

# Create system account for a service
sudo useradd -r -s /usr/sbin/nologin myservice

# Create system account with home directory
sudo useradd -r -m -d /var/lib/myservice myservice

-M or --no-create-home

Explicitly prevents home directory creation.

sudo useradd -M john

Use cases:

• System accounts
• Users who don’t need home directories
• Special purpose accounts

Advanced Configuration

Combining Multiple Options

Create a fully configured user account:

sudo useradd -m \
  -d /home/johnsmith \
  -s /bin/bash \
  -u 1500 \
  -g developers \
  -G sudo,docker,www-data \
  -c "John Smith - Senior Developer" \
  -e 2025-12-31 \
  john

What this does:

• Creates user “john”
• Creates home directory at /home/johnsmith
• Sets shell to /bin/bash
• Assigns UID 1500
• Sets primary group to “developers”
• Adds to groups: sudo, docker, www-data
• Sets full name comment
• Sets expiration date

Setting Defaults

View and modify default useradd settings:

# View current defaults
useradd -D

# View defaults in readable format
cat /etc/default/useradd

Common default settings:

• GROUP=100 – Default group
• HOME=/home – Default home directory base
• INACTIVE=-1 – Password expiration
• EXPIRE= – Account expiration
• SHELL=/bin/bash – Default shell
• SKEL=/etc/skel – Skeleton directory
• CREATE_MAIL_SPOOL=yes – Create mail spool

Modify defaults:

# Set default shell
sudo useradd -D -s /bin/zsh

# Set default home directory base
sudo useradd -D -b /home/users

# Set default group
sudo useradd -D -g 1000

# Set default skeleton directory
sudo useradd -D -k /etc/custom-skel

User Account Files

Understanding where user information is stored:

/etc/passwd

Contains user account information.

Format:

username:password:x:UID:GID:GECOS:home_directory:shell

Example entry:

john:x:1000:1000:John Smith:/home/john:/bin/bash

Fields:

1. username – Login name
2. password – Usually ‘x’ (stored in /etc/shadow)
3. UID – User ID
4. GID – Primary Group ID
5. GECOS – Full name/comment
6. home_directory – Home directory path
7. shell – Default shell

/etc/shadow

Contains encrypted passwords and password aging information.

Format:

username:encrypted_password:last_password_change:min_days:max_days:warn_days:inactive_days:expiration_date:reserved

View (requires root):

sudo cat /etc/shadow | grep john

/etc/group

Contains group information.

Format:

group_name:password:GID:user_list

Example:

developers:x:1001:john,jane,bob

/etc/gshadow

Contains group password and administrator information.

Practical Examples

Example 1: Standard User Account

Create a regular user with home directory and bash shell:

sudo useradd -m -s /bin/bash john
sudo passwd john  # Set password

Example 2: Developer Account

Create a developer with multiple group memberships:

# Create groups if they don't exist
sudo groupadd developers
sudo groupadd docker

# Create developer user
sudo useradd -m \
  -s /bin/bash \
  -g developers \
  -G sudo,docker,developers \
  -c "John Developer" \
  john

# Set password
sudo passwd john

Example 3: System Service Account

Create an account for a service/daemon:

sudo useradd -r \
  -s /usr/sbin/nologin \
  -d /var/lib/myservice \
  -c "My Service Account" \
  myservice

Example 4: Temporary User with Expiration

Create a user account that expires on a specific date:

sudo useradd -m \
  -e 2024-12-31 \
  -c "Temporary User" \
  tempuser

sudo passwd tempuser

Example 5: User with Custom Home Directory

Create user with home directory in non-standard location:

sudo useradd -m \
  -d /var/www/users/john \
  -s /bin/bash \
  john

# Verify
ls -la /var/www/users/john

Example 6: User with Specific UID

Create user with a specific UID (useful for consistency across systems):

# Check if UID is available
id 1500  # Should return "no such user"

# Create user with UID 1500
sudo useradd -m -u 1500 john

# Verify
id john  # Should show uid=1500

Example 7: User with Custom Skeleton Files

Set up custom files for new users:

# Create custom skeleton directory
sudo mkdir -p /etc/custom-skel
sudo cp /etc/skel/.bashrc /etc/custom-skel/
sudo cp /etc/skel/.profile /etc/custom-skel/

# Add custom files
sudo echo "alias ll='ls -lah'" >> /etc/custom-skel/.bashrc
sudo echo "export EDITOR=vim" >> /etc/custom-skel/.bashrc

# Create user with custom skeleton
sudo useradd -m -k /etc/custom-skel john

Troubleshooting

Common Issues and Solutions

Issue 1: “useradd: user ‘john’ already exists”

Problem: Username already exists in the system.

Solution:

# Check if user exists
id john

# If exists, use different username or delete existing user
sudo userdel john  # Then recreate

Issue 2: “useradd: group ‘developers’ does not exist”

Problem: Trying to assign user to non-existent group.

Solution:

# Create the group first
sudo groupadd developers

# Then create user
sudo useradd -m -g developers john

Issue 3: Home directory not created

Problem: User created but no home directory.

Solution:

# Create user with -m flag
sudo useradd -m john

# Or create manually and fix permissions
sudo mkdir /home/john
sudo chown john:john /home/john
sudo chmod 755 /home/john

Issue 4: “Permission denied”

Problem: Not running with root privileges.

Solution:

# Use sudo
sudo useradd john

# Or switch to root
su -
useradd john

Issue 5: UID already in use

Problem: Specified UID is already assigned.

Solution:

# Check UID usage
id 1500

# Use different UID or find available one
# Check /etc/passwd for used UIDs
cut -d: -f3 /etc/passwd | sort -n

Issue 6: User cannot login

Problem: User created but cannot login.

Possible causes:

• No password set
• Shell set to /usr/sbin/nologin or /bin/false
• Account expired
• Account locked

Solutions:

# Set password
sudo passwd john

# Check shell
getent passwd john | cut -d: -f7

# Change shell if needed
sudo usermod -s /bin/bash john

# Check account status
sudo chage -l john

Best Practices

1. Always Use Descriptive Comments

# Good
sudo useradd -m -c "John Smith - DevOps Engineer" john

# Bad
sudo useradd -m john

2. Set Appropriate Expiration Dates

For temporary accounts or contractors:

sudo useradd -m -e 2024-12-31 -c "Contractor Account" contractor

3. Use Appropriate Shells

• Regular users: /bin/bash or /bin/zsh
• System accounts: /usr/sbin/nologin or /bin/false
• Restricted users: /bin/rbash (restricted bash)

4. Organize Home Directories

Use consistent naming and structure:

# Standard location
sudo useradd -m -d /home/john john

# Or organized by department
sudo useradd -m -d /home/developers/john john

5. Set Up Groups Properly

Create groups before users when needed:

# Create groups first
sudo groupadd developers
sudo groupadd admins

# Then create users
sudo useradd -m -g developers -G admins john

6. Verify After Creation

Always verify user creation:

# Check user exists
id john

# Check home directory
ls -la /home/john

# Check groups
groups john

# Test login (if possible)
su - john

7. Document User Creation

Keep records of:

• Username and purpose
• UID/GID assignments
• Group memberships
• Expiration dates
• Special permissions

8. Use System Accounts for Services

For daemons and services:

sudo useradd -r -s /usr/sbin/nologin myservice

9. Set Password Policies

After creating user, configure password policies:

# Set password
sudo passwd john

# Configure password aging
sudo chage -M 90 john      # Max days
sudo chage -m 7 john       # Min days
sudo chage -W 7 john       # Warning days

10. Clean Up Unused Accounts

Regularly review and remove unused accounts:

# Check last login
last john

# Remove if unused
sudo userdel -r john  # -r removes home directory

---

Related Commands

usermod – Modify User Account

Modify existing user accounts:

# Change shell
sudo usermod -s /bin/zsh john

# Add to additional groups
sudo usermod -aG docker john

# Change home directory
sudo usermod -d /home/newhome john -m

# Lock account
sudo usermod -L john

# Unlock account
sudo usermod -U john

userdel – Delete User Account

Remove user accounts:

# Delete user (keeps home directory)
sudo userdel john

# Delete user and home directory
sudo userdel -r john

# Force delete (even if user is logged in)
sudo userdel -f -r john

passwd – Set/Change Password

Manage user passwords:

# Set password for user
sudo passwd john

# Change your own password
passwd

# Lock password
sudo passwd -l john

# Unlock password
sudo passwd -u john

chage – Change Password Aging

Configure password expiration:

# View password aging info
sudo chage -l john

# Set max password age
sudo chage -M 90 john

# Set min password age
sudo chage -m 7 john

# Set expiration date
sudo chage -E 2024-12-31 john

id – Display User ID Information

Show user and group IDs:

# Show current user info
id

# Show specific user info
id john

# Show only UID
id -u john

# Show only GID
id -g john

# Show all groups
id -G john

groups – Display Group Memberships

Show groups a user belongs to:

# Current user groups
groups

# Specific user groups
groups john

getent – Get Database Entries

Query system databases:

# Get passwd entry
getent passwd john

# Get group entry
getent group developers

# Get all users
getent passwd

Summary

Key Takeaways

1. useradd is the primary command for creating user accounts in Linux
2. Always use -m flag to create home directory (unless creating system accounts)
3. Set passwords separately using passwd command
4. Use -r flag for system/service accounts
5. Configure groups before or during user creation
6. Verify user creation after running the command
7. Document user accounts and their purposes
8. Use appropriate shells based on user type
9. Set expiration dates for temporary accounts
10. Follow best practices for security and organization

Quick Reference

# Basic user creation
sudo useradd -m username
sudo passwd username

# Full-featured user
sudo useradd -m -s /bin/bash -g groupname -G group1,group2 -c "Full Name" username

# System account
sudo useradd -r -s /usr/sbin/nologin servicename

# User with expiration
sudo useradd -m -e YYYY-MM-DD username

# Verify creation
id username
getent passwd username