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.
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:
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.
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.
Before making bulk or high-risk account changes, take a backup of the relevant account databases:
If something goes wrong, pwck and grpck can help identify inconsistencies in the account and group databases:
The backup gives you a known-good copy of the files before the change.
The basic syntax is straightforward:
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.
Before changing group membership, see what the account currently has:
After the change, verify it again:
You can also inspect the account’s supplementary groups directly:
This simple before-and-after check can catch a destructive -G mistake immediately.
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.
Verify the result with:
You should see something similar to:
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.
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.
Verify the new path:
The result should now contain:
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.
When you want usermod to change the home-directory path and move the existing home directory, combine -d with -m:
Then verify the destination:
For example:
Check several things before doing this on a production system.
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:
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.
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:
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.
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:
Also check user-specific scripts, application configuration, backup jobs, and other automation that may reference /home/tecmint.
The important distinction is:
Don’t use -d when you actually mean to perform a home-directory migration.
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:
Check the resulting account-aging settings with:
You should see something similar to:
These two settings are easy to confuse:
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:
To remove an account expiration date, pass an empty value:
-1 can also be used to clear the expiration date with versions of usermod that support that form:
Verify the result:
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.
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.
Check the current setting with:
You may see:
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:
Then set a seven-day inactivity window:
Now the policy is effectively:
To disable the inactivity feature again, use -1:
You can verify the complete password-aging policy with:
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:
Then change the user’s primary group:
Verify the change:
You should see something similar to:
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:
If the application requires the new group, update ownership deliberately:
Be careful with recursive chgrp on production data.
Changing group ownership indiscriminately can affect applications that depend on specific permissions.
Most Linux distributions create a user-private group with the same name as the account.
For example:
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:
might now show:
The old tecmint group can remain empty until you decide whether it is still needed.
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.
You should see:
The administrative group name differs by distribution:
Running -G without -a replaces the entire supplementary group list with the groups you specify.
For example:
This removes the user’s existing supplementary groups, including sudo, and leaves only docker.
There is a legitimate use for this behavior:
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.
Modern shadow-utils supports -r with -G to remove a user from a supplementary group without replacing their other group memberships.
You should see:
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:
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.
The -l option changes the user’s login name.
It does not automatically rename the home directory, private group, or mail spool.
You should see:
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:
If the private group also needs to be renamed:
And if the system uses a local mail spool that needs to follow the new login name:
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.
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.
You should see:
The path differs between distributions:
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.
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.
Check the existing UID before changing it:
For example:
Choose a new UID that isn’t already assigned to another account:
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:
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:
Here’s what each part does:
Run the search separately for other mounted filesystems where the user may have stored data.
The -o, –non-unique option allows you to assign a UID that is already in use:
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.
The -L option locks a user’s password by adding an exclamation mark (!) to the beginning of the password hash in /etc/shadow.
You may see:
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:
If you need to stop an account and its currently running processes, you need additional controls.
For example:
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.
To reverse the password lock and clear the account expiration:
You may see:
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.
The -p option expects an already-hashed password, not plaintext.
For example, this is wrong:
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:
It prompts for the password without putting it directly on the command line.
For scripted environments, chpasswd can read the credentials from standard input:
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:
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.
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:
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.
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:
Verify the ranges:
You should see:
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:
The short options are:
To remove the ranges:
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:
You should see an entry similar to:
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:
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.
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:
This command changes the user’s:
Verify each change separately:
You should see results similar to:
And:
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:
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.
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.
15 Practical pwd Examples in Linux You Should Know
8 chattr Commands to Make Files Immutable and Prevent Changes in Linux
20 DNF Commands Every Linux Administrator Should Know
12 Ways to Use the dmesg Command in Linux to View and Troubleshoot Kernel Messages
View and Manage Files using head, tail and cat Commands in Linux
16 Fun Linux One-Liners Every Command-Line User Should Try
I have a user in Debian 11 that I created through the GUI.
However, when I attempt to add this user to a group, it says the user does not exist.
I’ve successfully logged in to this user, so I’m unsure why it’s giving me this error.
How can I add multiple user example 200 users and the user should have a default password, must be forced to change password soon she logs in password expire after 30 days, and must have a sudo privilege and include user details
“We can assign UID between 0 to 999.”
As far as I know, you cannot.
UID of “0” is reserved for ‘root’ while UIDs 1-499 are reserved for system accounts.
@gragonmouth,
As per security standard it advised to use above 1000 UID/GID.
Moreover, 0-1000 reserved for System users by default in Systemd (RHEL 7, CentOS 7, Oracle Linux 7 etc.
)Linux servers.
Try to create a user and notice you will find UID/GID will be above >1000.
Thanks & Regards,
Babin Lonston
Then the UID number assignment depends on the distro you are using.
I use PCLinuxOS and the default starting UID number is 500.
From my distro-hopping days, I remember that some distros allow the admin to set the lowest allowable UID and/or the highest allowable UID.
Actually you can, but it is not recommended anyway…
try,
and this user will have now the same id as the root user.
Yep, the issue could happen if you assign that id, try on a virtual machine, and everything should be fine…
I changed the user home directory by usermod but bash_profile is not get there in the new home.
Since I tried to create it manually and did the changes in the file but the changes that I needed for is not working.
the bash profile worked fine in default home.
@Ankit,
Try to change the user default shell using following command.
What is the difference between passwd and usermod command, even passwd command can do the same things that usermod does.
for example if we want to lock the user account we can use either “#passwd -l username” or “#usermod -L username“.
@Anurag,
The passwd command change user password and whereas usermod command modified or rename username.
–inactive -f option sets a password expires, after which the account becomes completely disabled.
(-1) is disables this is the default.
Hi,
I last night created a hduser in single node Hadoop cluster in ubuntu and log out.
and can u tell me how to login to hduser again
Thank you……it was useful
Love this article.
Outstanding!
This is a quick shortcut to modify 4 settings in one line:
The scenario:
Say you have a user named ‘Bob’, and you want to change it to ‘Alice’.
Everytime you create users with the USERADD command, the system creates:
1.
The user name
2.
The group name
3.
The home directory
4.
etc…
all labeled as the new username:
User: Bob
Group: Bob
HomeDir: /home/Bob
If you only need to modify the names, then the following command will do the trick:
]# usermod -d /home/Alice -m -l Alice Bob && groupmod -n Alice Bob
Breaking the above command into smaller chunks:
usermod -d /home/Alice -m (this segment will rename the HomeDir and move (-m) the files into the new directory).
-l Alice Bob (this segment will change the username or login name.
Note that the parameter is a lowercase L).
&& groupmod -n Alice Bob (this segment will rename the group associated with the old username, to the new one).
If you are wondering what are the && symbols, they’re just the AND operator, that is:
the command at the left will be executed first, then the command at the right.
command1 && command2
This is a frequently administration task: rename user names.
My 2 cents!
I hope this will be useful 🙂
Chris.
@Chris,
Thanks for the detailed tip, hope it will be helpful to other users..
A very simple and easily understandably language.
@Reader,
Thanks for your valuable feedback.
nice tutorial
awesome tutorial !
fall in love with tecmint…!
thanks a lot…………..!
About the unencrypted password: An ordinary user doing a grep on /etc/shadow will get: permission denied.
That was the main idea about shadow with passwd being world readable and shadow only for root.
Tuned – Automatic Performance Tuning of CentOS/RHEL Servers
iPerf3 – Test Network Speed/Throughput in Linux
5 Tools to Scan a Linux Server for Malware and Rootkits
How to Create a Centralized Log Server with Rsyslog in CentOS/RHEL 7
How to Install Nagios Monitoring in RHEL, Rocky, and AlmaLinux
How to Install and Configure Zabbix Agents on Remote Linux – Part 3
How to Use ‘Yum History’ to Find Out Installed or Removed Packages Info
4 Useful Tools to Run Commands on Multiple Linux Servers
How to Find Deleted Files Still Eating Disk Space
How to Calculate IP Subnet Address with ipcalc Tool
4 Ways to Check Plugged USB Device Name in Linux
How to Find and Kill Running Processes in Linux
The 8 Best Free Anti-Virus Programs for Linux
12 Open-Source WYSIWYG Editors Worth Using in 2026
3 Best Document Collaboration Platforms for Linux in 2024
15 Best Tiling Window Managers for Linux in 2025
10 Top Open Source Artificial Intelligence Tools for Linux
8 Best Open Source Web Servers in 2024
—
**📚 Original Source:**
[usermod Command: Manage Linux Users, Groups, UID, Shell and More](https://www.tecmint.com/usermod-command-examples-linux/)
About The Author
