usermod is a command-line utility that allows you to modify a user’s login information.

This article covers how to use the usermod command to add a user to a group, change a user shell, login name, home directory, and more.

usermod Command

The syntax of the usermod command takes the following form:

Only root or users with sudo access can invoke usermod and modify a user account. On success, the command does not display any output.

Add a User to a Group

The most typical use case of the usermod is adding a user to a group.

To add an existing user to a secondary group, use the -a -G options followed the group’s name and the username:

usermod -a -G GROUP USER

If you want to add the user to multiple groups at once, specify the groups after the -G option separated with , (commas) with no intervening whitespace.

For example, to add the user linuxize to the games group, you would run the following command:

sudo usermod -a -G games linuxize

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

If the user or group doesn’t exist, the command will warn you.

Change User Primary Group

To change a user’s primary group, invoke the usermod command with by the -g option followed the group’s 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:

usermod -g developers linuxize

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

Changing the User Information

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

usermod -c "GECOS Comment" USER

Here is an example showing how to add additional information to the user linuxize:

usermod -c "Test User" linuxize

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

Changing a User Home Directory

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

If, for some reason, you want to change the user’ home directory invoke the usermod command with by the -d option followed the absolute path of the new home directory and the name of the user:

usermod -d HOME_DIR USER

By default, the command doesn’t move the content of the user’s home directory to the new one. To move the content, use the -m option. If the new directory does not already exist, it is created:

usermod -d HOME_DIR -m USER

Here is an example showing how to change the home directory of the user www-data to /var/www:

usermod -d /var/www www-data

Changing a User Default Shell

The default shell is the shell that is run after you log in to the system. By default, on most Linux systems, the default shell is set to Bash Shell.

To change the user’s default shell, run the command with the -s option followed the absolute path of the shell and the name of the user:

usermod -s SHELL USER

In the example below, we are changing the user shell to Zsh:

sudo usermod -s /usr/bin/zsh linuxize

You can find out what shells are available on your system by displaying the /etc/shells file’s content.

Changing a User UID

UID (the user identifier) is a number assigned to each user. It is used by the operating system to refer to a user.

To change the user UID, invoke the command with the -u option followed the new UID and the name of user:

usermod -u UID USER

The example below shows how to change the “UID” number to “1050”:

sudo usermod -u 1050 linuxize

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

Changing a User Name

Although not very often, sometimes you may want to change the name of an existing user. The -l option is used to change the username:

usermod -l NEW_USER USER

In the example below, we are renaming the user linuxize to lisa to “1050”:

sudo usermod -l linuxize lisa

When changing the username, you may also want to change the user’s home directory to reflect the new username.

Setting a User Expiry Date

The expiry date is the date on which the user account will be disabled. To set the user’s expiry date, use the -e option:

sudo usermod -e DATE USER

The expiry date must be set using the format YYYY-MM-DD.

For example, to disable the user linuxize on 2022-02-21, you would run the following command:

sudo usermod -e "2022-02-21" linuxize

To disable the expiration of an account, set an empty expiry date:

sudo usermod -e "" linuxize

Use the chage -l command to view the user’s expiry date:

sudo chage -l linuxize
Last password change					: Jul 24, 2018
Password expires					: never
Password inactive					: never
Account expires						: never
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 expiration date is stored in the /etc/shadow file.

Locking and Unlocking a User Account

The -L option allows you to lock a user account:

usermod -L USER

The commands will insert an exclamation point (!) mark in front of the encrypted password. When the password field in the /etc/shadow file contains an exclamation point, the user will not be able to login to the system using password authentication. Other login methods, like key-based authentication or switching to the user are still allowed. If you want to lock the account and disable all login methods, you also need to set the expiration date to 1.

The following examples shows how to lock the user linuxize:

sudo usermod -L linuxize
sudo usermod -L -e 1 linuxize

To unlock a user, run usermod with the -U option:

usermod -U USER

Conclusion

We have shown you how to use the usermod command to set user account information.

Feel free to leave a comment if you have any questions.