usermod Command in Linux: Modify User Accounts and Groups

usermod is a command-line utility for modifying user account attributes. You can use it to add a user to a group, change the default shell, rename a user, set an expiry date, lock or unlock an account, and more.

Only root or users with sudo access can invoke usermod. To create new users, see useradd . To remove users, see userdel .

usermod Command Syntax #

The syntax of the usermod command takes the following form:

usermod [OPTIONS] USER

On success, the command does not display any output.

Add a User to a Group #

The most common use of usermod is adding a user to a secondary group. Use the -a -G options followed by the group name and the username:

usermod -a -G GROUP USER

To add the user to multiple groups at once, specify the groups after -G as a comma-separated list with no spaces.

For example, to add the user linuxize to the games group:

sudo usermod -a -G games linuxize

Always use the -a (append) option when adding a user to a new group. If you omit -a, the user will be removed from every group not listed after -G.

The -a and -G options are often written together as -aG. The following command does the same thing:

sudo usermod -aG games linuxize

To verify the change, run:

id linuxize

uid=1000(linuxize) gid=1000(linuxize) groups=1000(linuxize),60(games)

The games group now appears at the end of the groups list. The user must log out and log back in before the new group applies to their session.

If the user or group does not exist, usermod prints an error such as usermod: group 'games' does not exist and makes no changes. For more on managing groups, see How to Add a User to a Group in Linux and How to Create Groups in Linux .

Removing a User from a Group #

To remove a user from a secondary group, use the -r option together with -G:

sudo usermod -r -G GROUP USER

For example, to remove the user linuxize from the games group:

sudo usermod -r -G games linuxize

The user is removed only from the listed group, and all other group memberships stay in place.

Older releases such as Ubuntu 22.04 ship a usermod without the -r option (it was added in shadow 4.10). On those systems, use the gpasswd command instead:

sudo gpasswd -d linuxize games

Change User Primary Group #

To change a user’s primary group, use the -g option followed by the group name and the username:

sudo usermod -g GROUP USER

In the following example, we are changing the primary group of the user linuxize to developers:

sudo usermod -g developers linuxize

The command also changes the group ownership of files in the user’s home directory that belonged to the old primary group.

Each user can belong to exactly one primary group and zero or more secondary groups.

Changing the User Information #

To change the GECOS field (the full name or description of the user), run the command with the -c option followed by the new comment and the username:

usermod -c "GECOS Comment" USER

Here is an example showing how to add a description to the user linuxize:

sudo usermod -c "Test User" linuxize

This information is stored in the /etc/passwd file.

Changing a User Home Directory #

On most Linux systems, user home directories are named after the username and created under /home.

To change the home directory, use the -d option followed by the absolute path of the new directory and the username:

usermod -d HOME_DIR USER

By default, the command does not move the contents of the old home directory to the new one. To move the contents, add the -m option. The new directory must not exist yet. usermod creates it and moves the files into it:

usermod -d HOME_DIR -m USER

Here is an example showing how to move the home directory of the user linuxize to /srv/linuxize:

sudo usermod -d /srv/linuxize -m linuxize

Without -m, only the path in /etc/passwd changes, and the files stay in the old directory.

Changing a User Default Shell #

The default shell is the shell that starts when you log in to the system. On most Linux systems, the default shell is Bash.

To change the default shell, use the -s option followed by the absolute path of the shell and the username:

usermod -s SHELL USER

In the following example, we are changing the login shell to Zsh:

sudo usermod -s /usr/bin/zsh linuxize

You can view the shells available on your system by reading the /etc/shells file.

Make sure the shell is installed before you switch to it. If the path does not exist, usermod prints a warning and changes the shell anyway:

usermod: Warning: missing or non-executable shell '/usr/bin/zsh'

The user will not be able to log in until the shell is installed. To install Zsh on Ubuntu, see How to Install and Use Zsh on Ubuntu .

Changing a User UID #

The UID (user identifier) is a number assigned to each user that the operating system uses to identify that user internally.

To change the UID, use the -u option followed by the new UID and the username:

usermod -u UID USER

The following example changes the UID of linuxize to 1050:

sudo usermod -u 1050 linuxize

The UID of files owned by the user and located in the user’s home directory and mailbox will be updated automatically. The ownership of all other files must be changed manually.

To find files that still belong to the old UID, search for it with find . For example, if the old UID was 1000:

sudo find / -xdev -uid 1000

The -xdev option keeps find on the root filesystem. Run the command again for other mount points, then fix the ownership with chown .

Changing a User Name #

To rename an existing user, use the -l option. The new username is specified first, followed by the current username:

usermod -l NEW_USER USER

In the following example, we are renaming the user linuxize to leah:

sudo usermod -l leah linuxize

When renaming a user, you may also want to rename the home directory to match. Use -d together with -m to move it:

sudo usermod -l leah -d /home/leah -m linuxize

The -l option renames only the user. The group with the same name as the user keeps the old name. To rename it, use the groupmod command:

sudo groupmod -n leah linuxize

To verify the rename, see How to List Users in Linux .

Setting a User Expiry Date #

The expiry date is the date on which the user account will be disabled. To set the expiry date, use the -e option followed by the date and the username:

sudo usermod -e DATE USER

The date must use the format YYYY-MM-DD. Other formats do not always produce an error. A day-first date such as 31-12-2026 is accepted, but it sets a different expiry date.

For example, to disable the user linuxize on 2026-12-31:

sudo usermod -e "2026-12-31" linuxize

Use the chage -l command to confirm the expiry date:

sudo chage -l linuxize

Last password change                                    : Oct 19, 2026
Password expires                                        : never
Password inactive                                       : never
Account expires                                         : Dec 31, 2026
Minimum number of days between password change          : 0
Maximum number of days between password change          : 99999
Number of days of warning before password expires       : 7

The Account expires line shows the new date.

To remove the expiry date and keep the account active indefinitely, set an empty string:

sudo usermod -e "" linuxize

When you run chage -l again, the Account expires line reads never.

The expiration date is stored in the /etc/shadow file.

Setting a User Password #

The -p option sets the password field in /etc/shadow. It expects an encrypted password, not plain text. If you pass plain text, usermod stores it as is, and the user cannot log in with that password.

Avoid using -p on the command line because the password hash is visible to users who can list process arguments. For interactive password changes, use passwd instead:

sudo passwd linuxize

The command prompts you to enter and confirm the new password. See How to Change User Password in Linux for details.

Locking and Unlocking a User Account #

The -L option locks a user account by inserting an exclamation point (!) in front of the encrypted password in /etc/shadow. This prevents password-based logins, but other methods such as SSH key-based authentication or switching users with su remain active.

To lock only the password:

sudo usermod -L linuxize

To lock the account completely and disable all login methods, combine -L with an expiry date of 1:

sudo usermod -L -e 1 linuxize

An expiry date of 1 means January 2, 1970, so the account is already expired.

To unlock a user account, use the -U option:

sudo usermod -U USER

The -U option does not change the expiry date. If you locked the account with -L -e 1, remove the expiry date in the same command:

sudo usermod -U -e "" linuxize

For password management options, see How to Change User Password in Linux .

Quick Reference #

For a printable quick reference, see the usermod cheatsheet .

Troubleshooting #

User is removed from all groups after running usermod -G
You omitted the -a flag. Without -a, the -G option replaces the user’s group list entirely. Always use -a -G together when adding to a group: usermod -a -G GROUP USER.

usermod: Permission denied. error
Running usermod as a regular user prints usermod: Permission denied. followed by usermod: cannot lock /etc/passwd; try again later. Run the command with sudo.

Wrong argument order with -l
The new username must come before the old username: usermod -l NEW_NAME OLD_NAME. If you reverse them, usermod looks for an account with the new name and fails with usermod: user 'leah' does not exist.

usermod: user USER is currently used by process PID error
The user is logged in or a process is running under that account. usermod will not change the username, UID, or home directory of an active user. Log the user out and stop any associated processes before modifying the account.

usermod: UID '1000' already exists error
The UID you specified is already assigned to another user. Choose a UID that is not in use, or check existing UIDs with getent passwd | cut -d: -f3 | sort -n.

Files stay in the old home directory after usermod -d -m
If the new directory already exists, usermod fails with usermod: directory /srv/linuxize exists. The new path is still written to /etc/passwd, and the files remain in the old directory. Point the account back to the old home directory with sudo usermod -d /home/linuxize linuxize, then repeat the move with a directory that does not exist.

New group does not apply to the current session
id USER shows the new group right away, but sessions that were already open keep the old group list. Log out and log back in, or start a shell with the new group using newgrp GROUP.

FAQ #

What is the difference between -g and -G?
-g changes the user’s primary group, the group assigned to new files by default. -G sets the list of supplementary groups. Always pair -G with -a to add to the list without replacing it.

How do I verify changes made by usermod?
Use id USERNAME to check UID, primary group, and supplementary groups. Use grep USERNAME /etc/passwd to check the shell and home directory. Use sudo chage -l USERNAME to review expiry settings. See How to List Users in Linux and How to List Groups in Linux for more options.

Can I change multiple settings in one command?
Yes. You can combine multiple options in a single usermod call. For example, to rename a user and move the home directory at the same time: usermod -l leah -d /home/leah -m linuxize.

Conclusion #

The usermod command handles most changes to an existing user account, including group membership, login shell, home directory, UID, username, expiry date, and lock state. Use id and chage -l after each change to verify the result.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 1000+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page