In this tutorial, we cover the basics of using the usermod command on a Linux-based distribution.
The usermod command is useful for modifying various settings associated with a user. For example, you can alter the user’s groups, change the user id, or lock their account. We go through some of the most common uses of this command in this tutorial.
You will need to ensure that the user you are editing is not performing any tasks, especially if you are editing the user ID, username, or home directory. You can close all the user’s tasks using the killall command, and you might also need to check their crontab.
This tutorial will take you through the various options you can use with the usermod command. We will also take you through a few examples of using the command to alter various user settings such as groups, login name, user ID, and much more.
Table of Contents
- usermod command Syntax
- usermod command Options
- Using the usermod Command
- More Help
usermod command Syntax
The syntax of the usermod command is easy to understand as it only accepts two parameters. However, there are several options that you can use with this command that I recommend learning.
usermod [OPTIONS] [LOGIN]
- [OPTIONS] is where you specify the options you want to set for the command. We cover the many options you can use in the text below.
- [LOGIN] is the username of the user you wish to modify.
usermod Command Options
There are quite a few different options that you can use with the usermod command. Below is a list of the popular available options. I recommend using the man command or inbuilt help documents for a complete list.
--badnamesallows the use of user names that do not meet standards.
--comment COMMENTsets a new comment in the GECOS field of the user.
--home HOME_DIRchanges the user’s home directory to a new location.
--login NEW_LOGINwill change the username to
NEW_LOGIN. Nothing else will be affected.
--move-homewill move the contents of the user’s home directory to the new location. You will need to use this option alongside
--home. Otherwise, it will not work.
--uid UIDwill change the user’s ID to the one specified. The ID will need to be unique unless you also use the
--non-uniqueoption. Changing the ID may require extra work to ensure all file permissions are updated correctly.
--non-uniqueis designed to be used alongside
-uidand will allow the user ID to be changed to a non-unique value.
--locklocks the user account by adding a
!in front of the user’s password.
--unlockdoes the opposite of the lock option and removes the
!from in front of the user’s password. It will unlock the user’s password but will not remove any expiry that you might have set.
--expiredate EXPIRE_DATEsets an expiry date for the user account. After expiry, the account will no longer be accessible. The date must be in the format of
--inactiveallows you to set the number of days after the password expires before an account is disabled. A value of
0disables the account immediately after expiry, and
-1disables the setting.
-gid GROUPoptions will change the user’s primary group. The group must already exist.
--groups GROUPSwill add the user to a list of supplementary groups. A comma must separate each group without any extra whitespace.
--appendoptions are to be used alongside the
-Goption. These options will add the user to the supplementary groups. Without these options,
-Gwill remove the user from any group that is not listed.
--root CHROOT_DIRmakes changes in the
CHROOT_DIRdirectory and uses configuration files from within the same directory.
--prefix PREFIX_DIRmakes changes in the
PREFIX_DIRdirectory and uses configuration files from within the same directory.
--shell SHELLallows you to change the path of the user’s login shell. Setting this to blank will make the system use the default login shell.
As I mentioned earlier, this is not all of the options you can use with this command. Use the inbuilt help options to see all available options.
Using the usermod Command
Using the usermod command is straightforward. However, remembering the many options and what they can do can be quite the task. Below we go through some of the more popular uses of the command.
You will need to be the root user or a user with superuser rights (sudo) to be able to use the usermod command. If you do not have the correct rights, you will likely receive errors in the terminal whenever you attempt to use the command.
Add a Comment to a User Account
You can add a comment to a specific user using the
--comment option. For example, you may want to include a comment containing contact information, the user’s real name, building and room number, their role, and much more.
The example below adds a simple comment to our pi user.
sudo usermod -c 'The Raspberry Pi User' pi
We can find our user and the newly added comment using the cat command.
dev@pimylifeup:~$ cat /etc/passwd pi:x:1001:1001:The Raspberry Pi User:/home/pi:/bin/bash
Change the Home Directory of a User
There are a few reasons why you may want to change the location of a user’s home directory. For example, you might not like the default home directory.
To change the home directory, simply use the
--home option followed by the path of the new directory.
sudo usermod -d /home/newDir pi
--home will not create the directory if it is missing and will not move any files. If you want to move the content, you can use the
--move-home option. Usermod will also create the directory if it does not already exist.
sudo usermod -m -d /home/newDir pi
The output below demonstrates the change when we move our user’s directory from pi to newDir using the
dev@pimylifeup:~$ ls /home/ dev pi dev@pimylifeup:~$ sudo usermod -m -d /home/newDir pi dev@pimylifeup:~$ ls /home/ dev newDir
Set an Expiry Date for a User Account
You can set an expiry date for when the user account will expire and become inaccessible. It is perfect if you only want the user’s account accessible for a specific time period. To do this, simply use the
--expiredate option followed by the date in the format of
sudo usermod -e '2022-06-10' exampleUser
You can use the chage command to see if the new expiry has been set for the user. As you can see in our output below, the account expires setting has our new date.
dev@pimylifeup:~$ sudo chage -l exampleUser Last password change : Jun 08, 2022 Password expires : never Password inactive : never Account expires : Jun 10, 2022 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
If you need to remove the expiry, simply use the same command but do not specify a date.
sudo usermod -e '' exampleUser
You can use the chage command to check that the expiry is now set back to never.
dev@pimylifeup:~$ sudo chage -l exampleUser Last password change : Jun 08, 2022 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
Change User’s Primary Group
You can use the usermod command with either the
--gid option to change a user’s primary group. Changing the user’s primary group can be helpful in situations where you want a set of users to share the same group.
This option will only work if the group exists, so you may need to create the group before adding the user.
Below is an example of how you can change the
exampleUser primary group to
sudo usermod -g www-data exampleUser
You can confirm the group has been changed by using the groups command followed by the username. Below is the output from before and after we ran the above command.
dev@pimylifeup:~$ groups exampleUser exampleUser : exampleUser dev@pimylifeup:~$ sudo usermod -g www-data exampleUser dev@pimylifeup:~$ groups exampleUser exampleUser : www-data
Add User to New Groups
You can add a user to multiple supplementary groups in a single command using the
You must include any current supplementary groups; otherwise,
usermod will remove them. To avoid this issue, use the
--append options if you want to prevent any existing groups from being removed.
In the example below, we add our
exampleUser to various groups. We do not use the
-a option, so any existing supplementary groups not listed will be removed.
sudo usermod -G adm,cdrom,sudo,dip,plugdev,lxd exampleUser
You can see all our newly added supplementary groups using the groups command. The first group on the list is our primary group which is not affected by the
dev@pimylifeup:~$ groups exampleUser exampleUser : www-data adm cdrom sudo dip plugdev lxd
Change Login Name
You can change the login name of a user by using the
--login options with the usermod command.
This option will change just the login and will not affect anything else. For example, the home directory will be under the original name, so you will need to update that separately.
In the example below, we change our exampleUser login to newUser.
sudo usermod -l newUser exampleUser
Using the cat command, you can confirm that the change has been made to the user. You will notice that nothing else has been changed with the user.
dev@pimylifeup:~$ cat /etc/passwd newUser:x:1002:33::/home/exampleUser:/bin/sh
Update User ID
You can alter a user’s ID by using the
--uid option with the command. You must ensure you pick an ID that is not assigned to another user or reserved for services, special, and system accounts.
The reserve range can vary depending on the Linux distribution you are using. Typically anything above 1000 should be fine, but it varies depending on the operating system. For example, Debian has ranges reserved higher than 60000.
It is also possible to assign a user a non-unique ID using the
--non-unique option. Using a non-unique ID means two users can share the same ID.
Usermod will update most permissions correctly after using this option. However, files and directories outside the home directory may need to be updated.
In the example below, we update our newUser id to 1010 using the usermod command and the
sudo usermod -u 1010 newUser
Using the id command with the
-u option, you can see that our user’s ID has been updated correctly.
dev@pimylifeup:~$ id -u newUser 1002 dev@pimylifeup:~$ id -u newUser 1010
Lock and Unlock User Account
You can lock and unlock an account using the usermod command. You need to use the
--lock options to lock an account. Alternatively, you will need to use
--unlock to unlock an account.
Locking an account using this method will change the password, so it has a
! in front of the encrypted password. This change results in the account being locked as the user will never be able to enter the correct password.
It is also recommended that you set the account’s expiration date to
1, as the
-L option will only block access with a password. You can set the expiry using the
Below is an example of how you can use usermod and the
--lock option to lock a user account.
sudo usermod -L newUser
You can use the
--unlock option with the command to unlock an account.
sudo usermod -U newUser
If you require more information on the command and its options, you can use either the manual command or view the inbuilt help documents.
To view the Linux manual pages for the command, simply use the
man command followed by
You can exit the manual pages by pressing the q key on your keyboard.
Alternatively, you can use the inbuilt help option by using the
--help option. You can also write the command without extra arguments for the same helpful information.
Either of the above methods should give you more information on some of the options you can use. However, I hope this tutorial has given you enough information that you will not need to use these methods.
I hope by now you have a decent understanding of how to use the usermod command and its many options. We have taken you through most of the options you are likely to use, but there is always more to learn.
We have plenty more tutorials on different Linux commands that I highly recommend you take the time to read. They cover many Linux topics such as user administration, file management, security, and much more.
Please let us know if you notice a mistake or an important topic is missing from this guide.