• United States
Unix Dweeb

How to modify user-account settings with usermod

Oct 28, 20206 mins

The usermod command allows you to make a lot of different changes to user accounts without having to carefully edit files like /etc/passwd, /etc/shadow and /etc/group. It's definitely worth your time to look into it.

Mobile users are seen within a virtual environment.
Credit: Gremlin / Getty Images

There are quite a few changes you can make to user accounts on Linux systems: setting them up, deleting or disabling them, adding or removing users from secondary groups, changing usernames or UIDs, moving home directories, changing users’ shells, altering account expiration timing, and so on.

One command that can make nearly all of these changes easier is usermod. The only real constraints are 1) that the accounts you intend to change must already exist on the system (this command won’t set them up from scratch), and 2) that the affected users should probably not be logged in when you make these changes.

The basic syntax for the command is usermod [options] LOGIN but that options section has a lot more possibilities than you might anticipate. In addition, sudo permissions will be required for this command since superuser access is required to set up or change nearly all user account settings.

While users can change their own passwords, select a different default shell and make changes to their environment settings (like their search paths), they cannot—at least not without root privileges—add themselves to groups, change their usernames, modify their descriptive information in the /etc/passwd file or make other changes to their account configuration. In fact, neither can they remove their accounts or lock their accounts without root access. Sysadmins have to make these changes for them.

With sudo access, on the other hand, you can make just about any changes to user accounts and with usermod, you can do it easily. Instead of editing files, you run commands that modify the files making the needed changes for you.

Let’s look at the long list of the options available with the usermod command and what they do.


The usermod command has so many options that the command almost run out of letters to express them. Here are some quick explanations of the options that show the range of changes this command can make:

  • -a used with -G appends the user to the specified group
  • -b allows names that don’t comply with standards
  • -c changes the comment field in the /etc/passwd file
  • -d changes a user’s home directory; with -m added, the contents of the old directory are moved into the new one
  • -e changes the user’s account expiration date (stored in the /etc/shadow file)
  • -f sets the number of days after a password expires that an account is disabled (stored in the /etc/shadow file)
  • -g changes the user’s group, provided the group to be assigned already exists
  • -G sets up the list of groups that the user will be a member of, removing other memberships unless -a is added
  • -l changes a user’s username
  • -L locks an account
  • -m moves the content of a user’s home to another location
  • -o when used with -u, allows a UID to have a value which is not unique
  • -p changes a user’s password (not recommended because it will show in ps output and the new password must be provided in encrypted form)
  • -P applies changes to the prefix directory
  • -R applies changes in the CHROOT_DIR directory
  • -s changes the user’s login shell
  • -u changes the user’s UID
  • -U unlocks a user’s password (removes the !)
  • -v adds subordinate UIDs to a user account
  • -V removes subordinate UIDs from a user account
  • -w adds subordinate GIDs to a user account
  • -W removes subordinate GIDs from a user account
  • -Z adds an SELinux user for an account (requires an SELinux-enabled kernel)

You could obviously make many of these kinds of changes by editing the related files as root. For example, you could change a username by replacing it in the /etc/passwd and /etc/shadow files and then change all instances of it in the /etc/group file. Still, a couple usermod commands could do the same thing and get the job done a lot quicker.

Here are some example usermod commands to show you how it works.

To add the user “dhart” to the group “secteam” on the system, you could do this:

$ sudo usermod -a -G secteam ghart

The group must already exist.

To change dhart’s username to dbell, you could use the command shown below. Notice the order of the arguments; the last argument is the one being changed.

$ sudo usermod -l dbell dhart
                   ^     ^
                   |     |
                  new   current

Note that this usermod command will update the /etc/passwd and /etc/shadow files.

To change Dory’s description in the /etc/passwd file, you can do this:

$ sudo usermod -c “Dory Bell” dbell
$ grep dbell /etc/passwd
dbell:x:1002:1002:Dory Bell:/home/dbell:/bin/bash

Note that changing Dory’s username will not automatically change her group even though these days most users’ primary groups are the same as their usernames. To rename Dory’s group, you could use a related groupmod command like this which changes the name of Dory’s group from dhart to dbell:

$ sudo groupmod -n dbell dhart
                    ^     |
                    |     |

Using a script

Are scripts still useful? Yes, of course they are! Even with efficient commands, it’s often challenging to remember which commands you need to use, never mind which order to put its arguments in.

In the script shown below, we want to make all the changes detailed in the commands above after a staff member returns from vacation only to tell us that she just got married and, thus, has a new surname. The following script will make all the changes, accommodating this person’s preferences with little effort on our part and confirm that they changes were made.


echo -n “current username: “
read oldname
echo -n “new username: “
read newname
echo -n “change user description field? [y/n] “
read ans
if [ $ans =="y" ]; then
    echo -n “Enter description> “
    read desc
    sudo usermod -c “$desc” $oldname
# change the user’s username in /etc/passwd and /etc/shadow files
sudo usermod -l $newname $oldname

# move the  user’s home to match the new username
sudo usermod -d /home/$newname -m $newname

# change the user’s group name
sudo groupmod -n $newname $oldnam

# verify the changes were made
echo /etc/passwd:
echo -n “  “
grep $newname /etc/passwd
echo home directory:
echo -n “  “
ls -ld /home/$newname

Here’s an example of the script in action:

$ update_user
current username: dhart
new username: dbell
change user description field? [y/n] y
Enter description> Dory Bell
  dbell:x:1002:1002:Dory Bell:/home/dbell:/bin/bash
home directory:
  drwxr-xr-x 8 dbell dbell 4096 Oct  6 11:44 /home/dbell

Once you put the needed commands into a script, you won’t have to work so hard at making sure your commands are correct, and you’ll still get the benefit of making the needed changes quickly and thoroughly.


Don’t forget that usermod offers a long list of options for making changes to user account settings. Some of them might make your work a bit easier.

Unix Dweeb

Sandra Henry-Stocker has been administering Unix systems for more than 30 years. She describes herself as "USL" (Unix as a second language) but remembers enough English to write books and buy groceries. She lives in the mountains in Virginia where, when not working with or writing about Unix, she's chasing the bears away from her bird feeders.

The opinions expressed in this blog are those of Sandra Henry-Stocker and do not necessarily represent those of IDG Communications, Inc., its parent, subsidiary or affiliated companies.

More from this author