Managing system users and their primary and secondary groups is one of the important tasks in Linux administration. The built-in usermod command does a great job with it.

This article will cover the usermod Linux command. We will first break down its syntax and options, and then move on to specific examples of its use that you may find useful.

Usermod Syntax and Options

The usermod utility is needed to manage Linux users, their primary and secondary groups. When you run it in the terminal, you need to specify the options and the specific user to whom the changes are applied. The syntax here is:

$ usermod options username

Consider the options that will be used in this article:

  • a , –append – add the user to one or more additional groups. The option will only work in conjunction with the -G option .
  • b , –badnames Allow badnames to be used.
  • d , –home Specify the new location of the user’s home directory. Using the -m option will move the contents of the current home directory to the new location.
  • e , –expiredate – Specify the date on which the account will be disabled. The date is entered in the format YYYY-MM-DD. If you use this option without specifying a date, the user’s disconnection will be cancelled.
  • f , –inactive – set the number of days for a user to be locked out after a password expires. A value of -1 disables the lock option, while a value of 0 will lock immediately after expiration.
  • g , –gid – select a new primary group for the user and for files in his home directory. You need to specify the name or number of the new group.
  • G , –groups – specify a list of additional groups that the user should belong to. Groups are separated by a comma. If the user is included in an additional group that was not specified in the list, then he will be removed from it. But when using the -a option , you can add new additional groups without removing the old ones.
  • l , –login Change the username to a new one. This option does not affect any other data. This means that the name of the home directory and mail will have to be changed manually so that they match the new username.
  • L , –lock – lock the user’s password. This option places a ! (exclamation mark) in front of the password in encrypted form, disabling it. This option cannot be used with -p and -U .
  • m , –move-home – change the location of the user’s home directory. The option will only work with -d . The utility will attempt to update file ownership and copy modes, ACLs, and extended attributes.
  • o , –non-unique – allow replacing the user ID with a non-unique value. Works in tandem with the -u option .
  • p , –password – change encrypted password.
  • R , –root – chroot into the specified directory and use it instead of the / root directory with configuration files stored in it.
  • s , –shell Specify a new shell for the user. Using the -s option with an empty value will select the default shell.
  • u , –uid – change the UID (numeric user identifier) ​​parameter. These changes will automatically be applied to the mailbox and the contents of the home directory. For other files, the UID will have to be changed manually.
  • U , –unlock – unlock the user’s password. This option removes the ! (exclamation point) in front of the password in encrypted form, allowing it to be used to log in. Will not work with -p and -L .

You can view all available options with the source description for this utility in the terminal by running the following command:

man usermod

This concludes the introductory part of the article. Now is the time to look at specific examples of using this utility to administer groups in Linux.

usermod examples

Let’s analyze typical tasks that may be useful for you to manage accounts on a computer or laptop.

1. Change main group

You can view a list of all groups available on the system in the /etc/group file , for example, using the vi editor in the terminal:

vi /etc/group

Linux usermod command

To change the main group, you need the -g option . The syntax here is:

$ usermod -g primary_groupname username

The task is to change the primary group for user test_user to test_group ( GID – 1001 ). This is what the command will look like in our case:

sudo usermod -g test_group test_user

Linux usermod command

You can then check that the changes have been applied using the id command. In the output of the id command, we are interested in the item GID. And instead of the name of the group, you can use its GID (1001 in our case):

sudo usermod -g 1001 test_user

2. Add to group

Let’s say the user gregory2 has limited rights, because it is used in rare cases for remote system management. It must be included in the plugdev group in order to have full access to external devices, such as USB hard drives. First, check its current groups with the command:

groups gregory2

Linux usermod command

The -G option will help with this task . But it must be used along with -a to add a new group without deleting the old ones:

sudo usermod -a -G plugdev gregory2

Linux usermod command

More detailed instructions on adding a user to a group using the usermod command are described in a separate article. Now you know how to add a user to the usermod group.

3. Remove from group

Next, let’s look at how to remove a user from the usermod group. This utility does not do a very good job of removing a user from groups, because the necessary option is simply not in it. But with -G you can specify in which additional groups the user will remain in order to remove all others.

Let’s take the already mentioned gregory2 account as an example . The goal is to leave it only in the disk group , removing cdrom and plugdev . In this case, you need to set the -G option for usermod and the group that will remain:

sudo usermod -G disk gregory2

Linux usermod command

And if you want to remove all additional groups for a particular user, pass the -G options to an empty value:

sudo usermod -G "" gregory2

Linux usermod command

We described in detail the removal of a user from a group in a separate article. In addition to the usermod utility, it covers working with gpasswd and deluser.

4. Change home folder

To see the current address of a particular user’s home folder, look at the contents of the /etc/passwd file , for example, using the grep utility:

grep gregory2 /etc/passwd

A specific directory is displayed with a / (slash) as the first character.

Linux usermod command

There are two scenarios worth considering separately here: choosing a different location for the home directory, and moving the current home directory and all of its contents to a new location.

If you just want to change the home folder, then use the -d option , specifying the new address. The utility will automatically create the folder if it doesn’t exist. Let’s take /home/new-dir as an example :

sudo usermod -d /home/new-dir gregory2

Linux usermod command

Let’s check the changes using the already mentioned grep utility:

grep gregory2 /etc/passwd

Linux usermod command

And if you want to move the home folder while keeping all the contents, then complement the -d option with the -m option , again specifying the new path. Let’s take /home/gregory-new as an example :

sudo usermod -m -d /home/gregory-new gregory2

Linux usermod command

You can check the location of the new folder using grep, and verify that the contents are copied using the Linux file manager.

5. Change shell

You can view the entire list of shells available on the system in the /etc/shells file . Open it in the vi editor:

vi /etc/shells

Linux usermod command

You can view the shell of a particular user in the already mentioned /etc/passwd file :

grep gregory2 /etc/passwd

The information you need comes after the home directory.

Linux usermod command

To change the shell, use the -s option . Let’s take the /usr/bin/dash shell as an example :

sudo usermod -s /usr/bin/dash gregory2

Linux usermod command

6. Change UID

UID is a numeric user ID. To view it, use the id utility :

id gregory2

Linux usermod command

You need the -u option to change this value . In this case, the new number must be non-negative (the number 0 is acceptable) and unique. Let’s take 9138 as an example:

sudo usermod -u 9138 gregory2

Linux usermod command

You can specify a non-unique UID number by adding the -o option to the original command . As an example, let’s take the identifier 0, which is assigned to the root group by default:

sudo usermod -o -u 0 gregory2

Keep in mind that these changes are automatically applied only to the home directory with its contents and to the mailbox.

7. Change login

To change the login (name) of the user, the -l option is intended . However, it does not affect the name of the home directory. If it suits you, then you can use it. Syntax:

$ sudo usermod -l new_name old_name

Here’s what it looks like with the user gregory2 , which needs to be renamed to gregory3 :

sudo usermod -l gregory3 gregory2

Linux usermod command

Well, you can also use this command along with moving the home folder, for example, to /home/gregory3 :

sudo usermod -l gregory3 -m -d /home/gregory3 gregory2

Linux usermod command

8. Change password

The –password option is for changing the password in encrypted form. Which means it’s not easy to use it. You need to add the openssl passwd command to it to encrypt the password. To change password to xz3 run:

sudo usermod --password $(openssl passwd -6 'xz3') gregory

Linux usermod command

As a result, password will change immediately after its execution.

9. Block user

To block a user, the -L option is useful , which blocks login with a password:

sudo usermod -L gregory2

When this option is used, an exclamation mark is added before the user’s password in the /etc/shadow file and the user will no longer be able to log in with the password. However, other login methods are still available. To completely block an account, add the –expiredate option with a value of 1 to the command:

sudo usermod --expiredate 1 -L gregory2

Linux usermod command

To cancel the lock in this case, the command with the options -U and -e with an empty value will work:

sudo usermod --expiredate "" -U gregory2

You can also use –expiredate to specify the exact expiration date in YYYY-MM-DD format. Here is what the team will look like for January 28, 2023:

sudo usermod --expiredate 2023-01-28 gregory2

You can view the account expiration date using the chage utility with the -l option :

sudo chage -l gregory2

Linux usermod command


The usermod linux command allows you to quite conveniently manage user groups, as well as change information about it. Well, if you want to understand the groups themselves and their devices in various Linux distributions in more detail, check out this material. It discusses this topic in detail, where the group file is stored, and other useful information.

Source: The article is distributed under the CC-BY-SA license