usermod Command: Manage Linux Users, Groups, UID, Shell and More

The usermod command modifies an existing user account. It’s the counterpart to useradd, which creates accounts. Rather than creating a new entry, usermod changes attributes associated with an account that already exists.

Everything below was tested on Ubuntu 26.04 with shadow-utils. Where behavior differs on RHEL-based systems, I’ve called it out.

What usermod Actually Changes on Disk

usermod doesn’t maintain a separate database of its own. Depending on the options you use, it modifies the account databases and configuration files under /etc. That makes changes relatively easy to inspect but also means a careless command can alter important account settings immediately.

Here are the files you’re most likely to encounter:

• /etc/passwd – account name, UID, primary GID, comment, home directory, and login shell.
• /etc/shadow – password hash and password/account aging information.
• /etc/group – supplementary group membership.
• /etc/gshadow – secure group information.
• /etc/subuid and /etc/subgid – subordinate UID/GID ranges used by rootless containers and user namespaces.
• /etc/login.defs – provides defaults such as UID_MIN and SUB_UID_COUNT; usermod reads these values for certain operations but does not normally modify the file.
• /etc/selinux/targeted/seusers – SELinux login mappings on systems configured with SELinux support.

The two subordinate-ID files /etc/subuid and /etc/subgid are particularly easy to overlook in older Linux guides. They matter on modern servers because rootless Podman, Docker, and other user-namespace-based workloads can depend on subordinate UID and GID ranges.

Before You Run usermod

There are four checks worth making before you touch a live account. usermod has no dry-run mode, and there is no built-in undo.

• You need sufficient privileges: Most account changes require root or sudo. A regular user cannot modify another account, and some operations on their own account also require elevated privileges.
• The account must already exist: usermod modifies existing accounts; it never creates users.
• Check for active sessions and processes: For operations such as -l, -u, -d, and -m, changing an account while it is actively being used can fail or create a messy transition. Log the user out and verify their processes are stopped before making these changes.
• Know where the account comes from: LDAP, Active Directory accounts managed through SSSD, and systemd-homed accounts are not necessarily managed through the local /etc/passwd database. usermod is for local accounts. Use homectl for systemd-homed accounts and your directory-management tools for centrally managed identities.

Back Up the Account Database First

Before making bulk or high-risk account changes, take a backup of the relevant account databases:

sudo mkdir -p /root/user-backup-$(date +%F)
sudo cp -a /etc/passwd /etc/shadow /etc/group /etc/gshadow 
  /root/user-backup-$(date +%F)/

If something goes wrong, pwck and grpck can help identify inconsistencies in the account and group databases:

sudo pwck
sudo grpck

The backup gives you a known-good copy of the files before the change.

usermod Syntax and Options

The basic syntax is straightforward:

usermod [options] LOGIN

The complexity comes from what each option changes and whether it replaces existing settings or adds to them.

The option that deserves special attention is -G. This command sudo usermod -G docker alice does not mean “add Alice to Docker.” It replaces Alice’s existing supplementary groups with docker.

To add docker while preserving her existing groups, use sudo usermod -aG docker alice. Think of it as -G = replace and -aG = append.

Check Before and After

Before changing group membership, see what the account currently has:

id alice

After the change, verify it again:

id alice

You can also inspect the account’s supplementary groups directly:

groups alice

This simple before-and-after check can catch a destructive -G mistake immediately.

1. Add or Update the User Comment Field

The -c option changes the GECOS field—the free-text account information commonly used for a user’s full name, office details, or other notes. It’s one of the least disruptive usermod options because it doesn’t change the user’s UID, groups, home directory, shell, or authentication settings.

sudo usermod -c "Ravi Saive, Content Team" tecmint

Verify the result with:

getent passwd tecmint

You should see something similar to:

tecmint:x:1001:1001:Ravi Saive, Content Team:/home/tecmint:/bin/bash

Use getent passwd rather than grepping /etc/passwd directly. getent queries the system’s configured name-service sources, so it can also return accounts supplied through services such as LDAP or SSSD.

The GECOS field can contain comma-separated subfields traditionally used for information such as full name, office location, work phone, and home phone. Avoid putting a colon (:) in the field because colons separate fields in /etc/passwd.

If you only need to edit a user’s GECOS information interactively, chfn is another option.

2. Change the Home Directory Path Only

The -d option changes the home-directory path stored in /etc/passwd. By itself, it does not move the existing directory, create the destination, or copy any files.

sudo usermod -d /srv/tecmint tecmint

Verify the new path:

getent passwd tecmint

The result should now contain:

tecmint:x:1001:1001:Ravi Saive, Content Team:/srv/tecmint:/bin/bash

This is where administrators often make a mistake: they use -d when they actually intend to migrate the user’s files.

If /srv/tecmint doesn’t exist, the next login can fail to change into the user’s home directory. The user may receive a message such as “Could not chdir to home directory” and end up in /, with their shell startup files, SSH configuration, and other dotfiles unavailable from the expected location.

Use -d by itself only when you’ve already moved or created the destination and are deliberately changing the path recorded for the account.

3. Move the Home Directory and Its Contents

When you want usermod to change the home-directory path and move the existing home directory, combine -d with -m:

sudo usermod -d /srv/tecmint -m tecmint

Then verify the destination:

ls -ld /srv/tecmint

For example:

drwxr-x--- 4 tecmint tecmint 4096 Sep  1 11:04 /srv/tecmint

Check several things before doing this on a production system.

Make sure the destination is suitable

The destination generally needs to be a path that usermod can move the existing home into. If the target already exists in a way that prevents the move, usermod will refuse the operation rather than merging the two directories.

Check the filesystem and available space before a large migration:

df -h /home /srv

If the source and destination are on different filesystems, the move may involve copying the data and then removing the original. For a large home directory, this can take considerable time and requires enough free space at the destination.

Check SELinux contexts

On RHEL, Rocky Linux, AlmaLinux, and other SELinux-enabled systems, moving a home directory to a non-standard location can leave files with an inappropriate SELinux context.

After the migration, restore the expected contexts:

sudo restorecon -Rv /srv/tecmint

The exact SELinux configuration depends on how the new home directory is being used, so don’t assume restorecon alone is sufficient for every custom home-directory layout.

Check for hard-coded paths

Changing the home-directory field doesn’t automatically update applications or configuration files that contain the old path. Before declaring the migration complete, search for references to the old location:

sudo grep -R "/home/tecmint" /etc/systemd/system /etc/cron* /etc/ssh 2>/dev/null

Also check user-specific scripts, application configuration, backup jobs, and other automation that may reference /home/tecmint.

The important distinction is:

• -d – Change where the system says the home directory is
• -d + -m – Change the path and move the existing home directory

Don’t use -d when you actually mean to perform a home-directory migration.

4. Set and Clear an Account Expiry Date

The -e option sets an account expiration date using the YYYY-MM-DD format. This is different from password expiration. Password aging controls when a password must be changed; account expiration disables the account itself after the specified date.

For example:

sudo usermod -e 2026-12-31 tecmint

Check the resulting account-aging settings with:

sudo chage -l tecmint

You should see something similar to:

Last password change                                    : Aug 24, 2026
Password expires                                        : never
Password inactive                                       : never
Account expires                                         : Dec 31, 2026
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

Account Expiry vs. Password Expiry

These two settings are easy to confuse:

• Account expiry – controls how long the account itself remains usable.
• Password expiry – controls how long the current password remains valid.

For contractors, temporary employees, interns, or short-lived service access, account expiry is particularly useful. Set the expiration date when you create or provision the account, and the account will automatically become unusable after that date instead of relying on someone to remember to disable it later.

For example:

sudo usermod -e 2026-12-31 contractor

Clear an Existing Expiry Date

To remove an account expiration date, pass an empty value:

sudo usermod -e "" tecmint

-1 can also be used to clear the expiration date with versions of usermod that support that form:

sudo usermod -e -1 tecmint

Verify the result:

sudo chage -l tecmint

The Account expires field should now show never.

For anything more detailed than a single cutoff date, chage handles the full aging policy, including minimum and maximum password age.

5. Set the Inactivity Window After Password Expiry

The -f option sets the number of days between password expiration and account deactivation. For example, setting it to 7 gives the user seven days after their password expires to log in and change it. After that inactivity period ends, the account is disabled.

sudo usermod -f 7 tecmint

Check the current setting with:

sudo chage -l tecmint | grep -i inactive

You may see:

Password inactive                                      : never

That can be confusing. The inactivity period only becomes meaningful when the account has a password expiration date. If the password is currently set never to expire, there is no expiration date from which the inactivity period can be counted.

For example, first configure the password to expire after 90 days:

sudo chage -M 90 tecmint

Then set a seven-day inactivity window:

sudo usermod -f 7 tecmint

Now the policy is effectively:

Password expires → 7-day inactivity window → Account disabled

To disable the inactivity feature again, use -1:

sudo usermod -f -1 tecmint

You can verify the complete password-aging policy with:

sudo chage -l tecmint

6. Change the Primary Group

Every user account has one primary group. By default, files created by the user inherit this group as their group ownership. The target group must already exist before you can assign it as the user’s primary group.

First, create the group:

sudo groupadd editors

Then change the user’s primary group:

sudo usermod -g editors tecmint

Verify the change:

id tecmint

You should see something similar to:

uid=1001(tecmint) gid=1002(editors) groups=1002(editors)

What Happens to Existing Files?

Changing the primary group affects the account’s future file creation, but you also need to think about existing files.

On current shadow-utils implementations, files in the user’s home directory that are owned by the user’s old primary group may have their group ownership updated as part of the operation. Files outside the home directory are not automatically converted just because the user’s primary group changed.

For example, if a service account has application data under /var/lib/myapp, changing its primary group does not mean you should assume all of that data has been reassigned to the new group.

Check ownership first:

sudo find /var/lib/myapp -group oldgroup -ls

If the application requires the new group, update ownership deliberately:

sudo chgrp -R editors /var/lib/myapp

Be careful with recursive chgrp on production data. Changing group ownership indiscriminately can affect applications that depend on specific permissions.

What Happens to the Old User-Private Group?

Most Linux distributions create a user-private group with the same name as the account. For example:

User:  tecmint
Group: tecmint

If you change the primary group to editors, the original tecmint group usually remains on the system even though it is no longer the user’s primary group.

That’s harmless by itself:

id tecmint

might now show:

uid=1001(tecmint) gid=1002(editors) groups=1002(editors)

The old tecmint group can remain empty until you decide whether it is still needed.

7. Add Supplementary Groups Without Wiping the Existing Ones

Supplementary groups grant users access to resources such as Docker, sudo, and other group-controlled services. When adding a user to supplementary groups, always combine -a with -G.

sudo usermod -aG docker,sudo tecmint
id -nG tecmint

You should see:

tecmint editors docker sudo

The administrative group name differs by distribution:

• Ubuntu / Debian: sudo usermod -aG sudo tecmint
• RHEL / Rocky / AlmaLinux / Fedora: sudo usermod -aG wheel tecmint

Running -G without -a replaces the entire supplementary group list with the groups you specify.

For example:

sudo usermod -G docker tecmint

This removes the user’s existing supplementary groups, including sudo, and leaves only docker. There is a legitimate use for this behavior:

sudo usermod -G "" tecmint

This removes all supplementary group memberships at once, but it should be done deliberately.

Group changes don’t affect sessions that are already open. The user needs to log out and back in for the new membership to take effect, or run newgrp docker to start a shell with the docker group as the current effective group.

8. Remove a User From a Supplementary Group

Modern shadow-utils supports -r with -G to remove a user from a supplementary group without replacing their other group memberships.

sudo usermod -rG docker tecmint
id -nG tecmint

You should see:

tecmint editors sudo

This avoids the older approach of manually listing every group the user should keep and applying the complete list again with -G. If you prefer dedicated group-management commands, gpasswd can perform the same operation:

sudo gpasswd -d tecmint docker

Revoking docker group membership should be followed by terminating the user’s existing sessions if you need the access removal to take effect immediately.

Group membership is evaluated when processes and connections are established, so an already-running session may retain the previous group membership.

9. Change the Login Name

The -l option changes the user’s login name. It does not automatically rename the home directory, private group, or mail spool.

sudo usermod -l tecmint_admin tecmint
id tecmint_admin

You should see:

uid=1001(tecmint_admin) gid=1002(editors) groups=1002(editors),27(sudo)

The home directory keeps its old name, the user-private group keeps its old name, and the mail spool under /var/mail is not renamed automatically. If you want to rename the account and its home directory as part of the same change:

sudo usermod -l tecmint_admin -d /home/tecmint_admin -m tecmint

If the private group also needs to be renamed:

sudo groupmod -n tecmint_admin tecmint

And if the system uses a local mail spool that needs to follow the new login name:

sudo mv /var/mail/tecmint /var/mail/tecmint_admin

The user must be fully logged out before changing the login name. Check for running processes first pgrep -u tecmint and if a process is still running under the account, usermod may refuse the operation with an error such as usermod: user tecmint is currently used by process 1234.

10. Change the Login Shell

The -s option sets the shell that runs when a user logs in. The most common real-world use isn’t switching someone from Bash to Zsh. It’s removing interactive shell access from a service account.

sudo usermod -s /usr/sbin/nologin backupsvc
getent passwd backupsvc

You should see:

backupsvc:x:998:998:Backup Agent:/var/lib/backupsvc:/usr/sbin/nologin

The path differs between distributions:

• Ubuntu / Debian: /usr/sbin/nologin
• RHEL / Rocky / AlmaLinux: /sbin/nologin

The /usr/sbin/nologin displays a message and exits, while /bin/false exits silently with a non-zero status. Both prevent interactive shell login.

However, changing the login shell alone does not necessarily block every type of remote access. SSH port forwarding or SFTP may require additional restrictions in sshd_config, depending on how the account is configured.

Unlike chsh, usermod does not require the shell to appear in /etc/shells. Check that the path exists before applying the change ls -l /usr/sbin/nologin and then make the change sudo usermod -s /usr/sbin/nologin backupsvc.

11. Change the UID and Fix File Ownership

Changing a user’s UID is one of the more sensitive usermod operations because Linux file ownership is stored as numeric UIDs, not usernames.

A common mistake is assuming that regular users always have UIDs below 1000. They generally do not.

• UID 0 belongs to root.
• UIDs 1–999 are normally reserved for system and service accounts, with the exact range controlled by SYS_UID_MIN and SYS_UID_MAX in /etc/login.defs.
• Regular users normally start at UID_MIN, commonly 1000 on modern distributions.

Check the existing UID before changing it:

id babin

For example:

uid=1002(babin) gid=1003(babin) groups=1003(babin)

Choose a new UID that isn’t already assigned to another account:

getent passwd 1500

If the command returns nothing, UID 1500 isn’t currently present in the configured passwd sources. Now change the UID using sudo usermod -u 1500 babin and Verify it with id babin.

You should now see:

uid=1500(babin) gid=1003(babin) groups=1003(babin)

Find Files Still Owned by the Old UID

When the UID changes, files owned by the user inside their home directory may be updated automatically. Files elsewhere on the system that still carry the old numeric UID are not automatically fixed. In this example, the old UID was 1002:

sudo find / -xdev -uid 1002 -exec chown -h babin {} +

Here’s what each part does:

• find / starts searching from the filesystem root.
• -xdev keeps the search on the current filesystem instead of crossing into other mounted filesystems.
• -uid 1002 finds files whose numeric owner is still the old UID.
• -exec chown -h babin {} + changes ownership in batches, with -h operating on symbolic links themselves rather than following them.

Run the search separately for other mounted filesystems where the user may have stored data.

Avoid Duplicate UIDs

The -o, --non-unique option allows you to assign a UID that is already in use:

sudo usermod -u 1500 -o babin

This breaks the normal one-to-one relationship between a username and a numeric UID. Files owned by UID 1500 can then appear to belong to multiple accounts. Treat -o as a migration or compatibility option, not something to use for normal UID changes.

12. Lock and Unlock an Account

The -L option locks a user’s password by adding an exclamation mark (!) to the beginning of the password hash in /etc/shadow.

sudo usermod -L babin
sudo getent shadow babin | cut -d: -f2

You may see:

!$y$j9T$rH2kQ...

This is one of the most misunderstood usermod options. Locking the password does not disable the account itself. It prevents authentication using the locked password, but other forms of access may remain available.

For example:

• SSH key authentication can still work.
• su - babin from root can still work.
• Existing sessions continue running.
• Cron jobs owned by the user continue running.

If you need to stop an account and its currently running processes, you need additional controls. For example:

sudo usermod -L -e 1 babin
sudo pkill -KILL -u babin
sudo mv /home/babin/.ssh/authorized_keys /home/babin/.ssh/authorized_keys.disabled

The first command locks password authentication and sets the account to an expired state. The second terminates processes owned by the user, while the third disables the user’s SSH authorized keys.

Unlock the Account

To reverse the password lock and clear the account expiration:

sudo usermod -U -e "" babin
sudo passwd -S babin

You may see:

babin P 08/24/2026 0 99999 7 -1

If the account never had a password, usermod -U may warn that unlocking it would leave a passwordless account and refuse to proceed. In that situation, set a password with passwd instead.

13. Set a Password the Right Way

The -p option expects an already-hashed password, not plaintext.

For example, this is wrong:

sudo usermod -p redhat pinky

It writes the literal string redhat into the password field rather than a valid password hash. The command may appear to succeed, but the user won’t be able to authenticate with redhat.

For interactive use, passwd is the correct and safest choice:

sudo passwd babin

It prompts for the password without putting it directly on the command line. For scripted environments, chpasswd can read the credentials from standard input:

echo 'babin:S3cret-Passphrase' | sudo chpasswd

However, be careful with this form because the plaintext password can still end up in shell history or other places depending on how the command is executed. For sensitive production automation, use a safer secret-handling mechanism rather than hard-coding passwords in scripts.

If you genuinely need usermod -p, generate the password hash first:

HASH=$(openssl passwd -6)
sudo usermod -p "$HASH" babin

openssl passwd -6 prompts for the password and generates a SHA-512 password hash. The resulting hash is stored in the HASH shell variable, rather than putting the plaintext password directly on the command line.

usermod -p then writes that hash into /etc/shadow.

Password-hash defaults can differ between distributions. Ubuntu and Debian commonly use yescrypt, producing hashes beginning with $y$. You can generate a yescrypt hash with:

mkpasswd -m yescrypt

On many RHEL-based systems, SHA-512 remains the traditional default, producing hashes beginning with $6$.

Both formats can work across distributions when the underlying libcrypt implementation supports them, but using the distribution’s normal hashing method keeps the configuration consistent.

14. Add Subordinate ID Ranges for Rootless Containers

This option is missing from many older usermod tutorials, but it matters for modern rootless container setups. Rootless Podman and Docker can map container UIDs and GIDs to a block of subordinate IDs assigned to the host user.

For example:

sudo usermod --add-subuids 200000-265535 --add-subgids 200000-265535 tecmint
grep tecmint /etc/subuid /etc/subgid

Verify the ranges:

grep tecmint /etc/subuid /etc/subgid

You should see:

/etc/subuid:tecmint:200000:65536
/etc/subgid:tecmint:200000:65536

A range of 65,536 IDs is commonly used for rootless container UID/GID mappings.

Make sure subordinate-ID ranges don’t overlap with ranges assigned to other users. On systems where multiple users run rootless containers, keep track of the ranges you’ve allocated.

After changing subordinate ID ranges, rootless container environments may need to be migrated so existing containers use the updated mapping:

podman system migrate

The short options are:

• -v / --add-subuids – add a subordinate UID range.
• -V / --del-subuids – remove a subordinate UID range.
• -w / --add-subgids – add a subordinate GID range.
• -W / --del-subgids – remove a subordinate GID range.

To remove the ranges:

sudo usermod --del-subuids 200000-265535 
  --del-subgids 200000-265535 tecmint

15. Map an Account to an SELinux User

On RHEL, Rocky Linux, AlmaLinux, Fedora, and other systems with SELinux enabled, the -Z option assigns an SELinux user to a Linux account.

For example:

sudo usermod -Z staff_u babin
sudo semanage login -l

You should see an entry similar to:

Login Name           SELinux User         MLS/MCS Range        Service
__default__          unconfined_u         s0-s0:c0.c1023       *
babin                staff_u              s0-s0:c0.c1023       *
root                 unconfined_u         s0-s0:c0.c1023       *

The SELinux user determines the security context assigned to the account when it logs in. Mapping an account to staff_u or user_u can provide tighter restrictions than the default unconfined_u, depending on the system’s SELinux policy.

To remove an explicit SELinux login mapping:

sudo usermod -Z "" babin

Ubuntu uses AppArmor by default rather than SELinux, so -Z is generally not relevant unless SELinux has been deliberately installed and enabled.

Newer versions of shadow-utils also support --selinux-range for systems using SELinux MLS/MCS ranges.

16. Modify Several Attributes in One Command

usermod allows you to combine multiple options in a single command. This can be useful when provisioning or updating an account because you can make several related changes together.

For example:

sudo usermod -d /srv/jack -m -s /bin/bash -e 2026-12-10 -f 7 
  -c "Jack Wallen, DevOps" -u 1600 -aG sudo,docker jack

This command changes the user’s:

• Home directory and moves its contents.
• Login shell.
• Account expiration date.
• Password inactivity period.
• GECOS comment.
• UID.
• Supplementary group memberships.

Verify each change separately:

getent passwd jack
id jack
sudo chage -l jack

You should see results similar to:

jack:x:1600:1004:Jack Wallen, DevOps:/srv/jack:/bin/bash
uid=1600(jack) gid=1004(jack) groups=1004(jack),27(sudo),988(docker)

And:

Account expires                                         : Dec 10, 2026

Be Careful With Combined Changes

A combined usermod command is not a transaction. If an operation fails, don’t assume every requested change was rolled back. Earlier changes may already have been applied. For that reason, test complex commands against a throwaway account on a test system before using them on production accounts.

For offline systems, such as a rescue environment or a mounted filesystem image, -R can apply the change relative to a specified root directory:

sudo usermod -R /mnt/sysroot -s /bin/bash jack

The -P option can also be used to apply changes to a prefix directory without performing a chroot operation. These options are useful when repairing or modifying accounts from live media.

Common usermod Errors and What They Mean

Conclusion

usermod looks simple on the surface, but it can change almost every important part of an existing Linux account—from its groups, UID, and home directory to password policies, login shell, account expiry, and even subordinate IDs for rootless containers.

The most important habit is to check before you change. Back up the account databases, verify the user’s current configuration, use -a with -G when adding supplementary groups, and always verify the result after making changes.

Run sudo pwck and sudo grpck after any batch of account changes. They can catch problems such as invalid account entries, inconsistent group information, and other account-database issues that can build up when several administrators manage users on the same system.

If usermod behaves differently on your distribution than it did here, share this guide with the next person who’s about to run it on a production account—especially if there’s no backup of /etc/shadow.

Once you’re comfortable modifying accounts, the next commands worth knowing are userdel for removing users, gpasswd for group administration, and passwd -e for forcing a password change at the next login.