usermod Command in Linux: A Practical How-To Guide

The Linux usermod command changes settings for an existing user account, such as its login name, home directory, shell, or group memberships. You need administrative privileges, usually through sudo, and should check the account details before making changes because some changes affect the user’s next login or access to files.

What You’ll Need

A Linux system with the usermod command installed (it is commonly provided by the system’s account-management tools).
A root account or an account allowed to run commands with sudo.
The exact username and the change you intend to make. For group changes, know whether you want to add supplementary access or replace existing supplementary groups.
If changing a home directory or login name, plan for the user to be logged out. Back up important data before moving or reorganizing a home directory.

Step-by-Step

Check the account and current settings. Confirm the username is correct and inspect its details before editing. For example, run id alice to see the user’s UID and groups, and getent passwd alice to view the account record, including its home directory and login shell. Replace alice with the actual username. If the command returns no account, stop and check the spelling or whether the account is local.
Choose the right command option. The basic pattern is sudo usermod [options] username. Use one or more options before the final username. Read the local manual with man usermod if you need to check an option or distribution-specific behavior. Avoid editing account database files directly while using this command.
Add a user to a supplementary group without removing other groups. Use sudo usermod -aG groupname alice, replacing both names as needed. The -G option specifies supplementary groups, while -a appends the group instead of replacing the existing supplementary group list. For example, sudo usermod -aG developers alice adds the account to developers. The user may need to log out and back in before a new session reflects the change.
Replace supplementary group memberships only when intended. The command sudo usermod -G group1,group2 alice sets the supplementary group list to the groups provided. It does not append. Leaving out a group can remove the account’s access to resources associated with that group, so first record the current list with id alice. Include every supplementary group the user should retain. The user’s primary group is managed separately.
Change the account’s primary group if required. Use sudo usermod -g groupname alice to set a new primary group. Check that the group exists with getent group groupname. Changing the primary group does not automatically change ownership of the user’s existing files. Review file ownership and access requirements separately before making related changes.
Change the login shell. Run sudo usermod -s /bin/bash alice, substituting a valid shell path and username. Check available shells with cat /etc/shells where that file is present. A shell change affects future login sessions; it does not necessarily change a currently open terminal.
Change the home directory, with an optional move. To update the recorded home path and move the contents from the old home directory, use sudo usermod -d /home/newname -m alice. The -d option sets the new path and -m requests moving the contents. Check that the destination is appropriate and that the user is logged out first. Without -m, the account record changes but the existing files are not moved. Do not assume this command relocates files stored outside the home directory.
Change the login name carefully. Use sudo usermod -l newname oldname. The final argument is the existing account name; -l provides its new login name. This changes the login name, but does not by itself rename the home directory or update every reference to the old name. Plan any home-directory move separately, and check services, scheduled tasks, scripts, and file ownership that may refer to the old account.
Apply the change and verify it. For changes that affect a running account, have the user log out first; do not change an account while it is being used by active processes if the operation could disrupt them. After running the command, check with id alice and getent passwd alice, using the new name if you renamed the account. For a shell or home-directory change, confirm the relevant field. Test the intended login or access in a new session before considering the task complete.

Common Mistakes

Using -G without -a. This replaces the supplementary group list. Use -aG to add a group while preserving existing memberships.
Putting the username in the wrong position. The target account goes at the end of the command. Double-check it before pressing Enter, especially in scripts or when renaming.
Expecting a group change to take effect in an existing session. Existing processes retain their current group credentials. Log out and start a new session to test the change.
Assuming a name or home change updates everything. A login rename does not automatically rename the home directory or revise references in applications, services, or files.
Using an invalid shell or nonexistent group. Check the shell path and group name first. A typo can prevent the intended configuration or account access.

Tips

Use id and getent passwd before and after changes to compare the account’s actual settings.
Make one planned change at a time when possible. This makes it easier to identify which option caused an unexpected result.
Use sudo for a single administrative command rather than switching to a root shell unnecessarily.
For a group addition, write the option as -aG and provide supplementary group names separated by commas, with no spaces.
Keep a record of the previous group list and account values when changes could affect access or login behavior.

Troubleshooting

“Permission denied” or a message requiring root: Run the command with sudo if your account is authorized, or ask an administrator to make the change. Do not try to work around system permissions.

“User does not exist” or no output from lookup: Check the username’s spelling and capitalization. Use getent passwd username to determine whether the system can find the account. If the account is managed by a directory service, local account tools may not be the correct way to change it; follow that service’s administration process.

The user lost access to a group’s resources: Check id username. If an earlier command used -G without -a, the old supplementary memberships may have been replaced. Restore the complete intended list with sudo usermod -G group1,group2 username, or add a missing group with sudo usermod -aG groupname username. Verify the group list and start a fresh login session.

The home directory did not move: Confirm that you used both -d and -m, that the destination is valid, and that the user was not active during the operation. Check the account’s recorded path with getent passwd username and inspect the old and new directories. Do not delete the old data until you have verified the files and access.

A shell or login change seems ineffective: Confirm the account record, then test with a new login session. A change to account settings cannot alter an already-running session. If login fails, use an administrator account to check the shell path and restore a valid shell.

Frequently Asked Questions

Does usermod create a new user?
No. It modifies an existing account. Use your system’s user-creation tool to create a new account.

What is the difference between -G and -aG?
-G sets the supplementary group list. Adding -a appends the specified group or groups instead of replacing that list.

Can I change a user’s settings while they are logged in?
Some changes can be recorded, but active processes may keep old settings, and changing an account in use can cause problems. Have the user log out before changes that affect their login, home directory, or running processes.

Does changing the login name rename the home directory?
No. The -l option changes the login name only. Change the home path separately with -d, and use -m if you intend to move its contents.

How do I undo a usermod change?
Run the relevant option again with the previous value. For group changes, restore the complete intended supplementary group list. Verify the result and remember that a configuration change may not reverse file moves or other changes made separately.

Where can I see all usermod options?
Run man usermod on the system. The manual describes the options supported by that installation.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →