usermod is the command for changing an existing user account in Linux. With it you add a user to groups, rename them, move the home directory, change the shell and temporarily lock access.

All the commands below are run as root or through sudo. We checked them on Debian 12; they work the same on Ubuntu and other distributions.

Create a user, not change one

If the user does not exist yet, create them first.
On Ubuntu and Debian the command is adduser name.
On AlmaLinux and CentOS it is useradd -m name.

An example of a separate user for SSH login is in the article on SSH key login.

---

How to view a user's current settings

Before any change it helps to check what the user has now.

# UID, primary group and all supplementary groups of the user
id username

# The user's line from /etc/passwd: home directory and shell
getent passwd username

---

Add a user to a group

This is the most common task, for example to grant administrator rights through sudo or access to Docker.

# Add the user to the sudo group (on Ubuntu and Debian)
usermod -aG sudo username

# On AlmaLinux, CentOS and Oracle Linux admins are in the wheel group
usermod -aG wheel username

# List several groups at once, separated by commas with no spaces
usermod -aG docker,www-data username

Do not forget the -a flag

-G without -a replaces the whole list of supplementary groups. The user ends up only in the groups you listed and loses the rest, for example access to sudo. To add, always write -aG.

New groups take effect at the user's next login. If they are connected over SSH right now, have them reconnect and then check the result with id.

---

Remove a user from a group

# Remove the user from the docker group
gpasswd -d username docker

The same result comes from usermod -rG docker username, but the gpasswd version works in every distribution.

---

Change the primary group

Every user has one primary group. New files the user creates get that group.

# Make developers the user's primary group. The group must already exist
usermod -g developers username

---

Rename a user

The -l flag changes only the login. The home directory and personal group keep their old names, so they are usually renamed together with the login.

# Change the login olduser to newuser
usermod -l newuser olduser

# Move the home directory to the new name along with its contents
usermod -d /home/newuser -m newuser

# Rename the user's personal group
groupmod -n newuser olduser

The user must not be logged in

You cannot rename a user who has running processes. Ask them to log out or end their sessions, then repeat the command.

---

Move the home directory

# Set a new home directory and move all files into it
usermod -d /data/home/username -m username

Without -m, only the path in the settings changes, and the files stay in the old place.

---

Change the shell

# List the shells installed in the system
cat /etc/shells

# Make bash the user's shell
usermod -s /bin/bash username

# Forbid console login, for example for a service user
usermod -s /usr/sbin/nologin username

---

Lock and unlock a user

# Lock password login
usermod -L username

# Remove the lock
usermod -U username

# Fully disable the account by setting an expiry date in the past
usermod -e 1 username

# Remove the expiry date
usermod -e "" username

Locking the password does not close key login

usermod -L forbids password login only. If the user has an SSH key set up, they can still log in. To close access completely, use usermod -e 1 or remove their keys from ~/.ssh/authorized_keys.

---

Change the UID

# Assign the user UID 1050. The number must not be taken
usermod -u 1050 username

usermod changes the owner of files in the user's home directory on its own. Files elsewhere keep the old UID; you can find and fix them like this.

# Instead of 1001, put the user's old UID
find / -xdev -user 1001 -exec chown -h username {} \;

---

Cheat sheet

Command	What it does
usermod -aG group name	Add to a supplementary group
gpasswd -d name group	Remove from a group
usermod -g group name	Change the primary group
usermod -l new old	Rename the user
usermod -d path -m name	Move the home directory
usermod -s shell name	Change the shell
usermod -L name / -U	Lock or unlock the password
usermod -e 1 name	Fully disable the account
usermod -u UID name	Change the UID

---

Frequently asked questions

I added the user to a group but the rights did not appear

Groups apply at login. The user needs to log out and back in, after which id will show the new group.

It says the group does not exist

Create the group first with groupadd group_name, then run usermod again. You can see all groups with getent group.

I cannot rename the user

Most likely the user is logged in or has running processes. Look at them with ps -u username, end the sessions and repeat usermod -l.

I accidentally ran usermod -G without -a

The user is left only in the groups you listed. Restore the needed groups with the same command and the -aG flag, for example usermod -aG sudo username. If this was your only administrator and sudo access is gone, log in to the server as root through the Console button in the client area.

---

Our resources

Telegram channel: https://t.me/f3cloud_news
Our website: https://f3cloud.com