Back to Commands

usermod

user managementLinux/Unix
The usermod command is one of the most frequently used commands in Linux/Unix-like operating systems. usermod Modify a user account
See ExamplesView Syntax

Quick Reference

Command Name:

usermod

Category:

user management

Platform:

Linux/Unix

Basic Usage:

usermod [options] [arguments]

Common Use Cases

    Syntax

    usermod [options] LOGIN

    Options

    Option Description
    -a, --append Append the user to the supplemental groups mentioned by the -G option without removing the user from other groups
    -c, --comment COMMENT New value of the GECOS field
    -d, --home HOME_DIR New home directory for the user account
    -e, --expiredate EXPIRE_DATE Set account expiration date to EXPIRE_DATE (YYYY-MM-DD format)
    -f, --inactive INACTIVE Set password inactive after expiration to INACTIVE days
    -g, --gid GROUP Force use GROUP as new primary group
    -G, --groups GROUPS New list of supplementary GROUPS
    -h, --help Display help message and exit
    -l, --login NEW_LOGIN New value of the login name
    -L, --lock Lock the user account
    -m, --move-home Move contents of the home directory to the new location (use only with -d)
    -o, --non-unique Allow using duplicate (non-unique) UID
    -p, --password PASSWORD Use encrypted password for the new password
    -R, --root CHROOT_DIR Directory to chroot into
    -P, --prefix PREFIX_DIR Prefix directory where are located the /etc/* files
    -s, --shell SHELL New login shell for the user account
    -u, --uid UID New UID for the user account
    -U, --unlock Unlock the user account
    -v, --add-subuids FIRST-LAST Add range of subordinate uids
    -V, --del-subuids FIRST-LAST Remove range of subordinate uids
    -w, --add-subgids FIRST-LAST Add range of subordinate gids
    -W, --del-subgids FIRST-LAST Remove range of subordinate gids
    -Z, --selinux-user SEUSER New SELinux user mapping for the user account

    Examples

    How to Use These Examples

    The examples below show common ways to use the usermod command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

    # Basic Examples Basic
    # Change a user's home directory sudo usermod -d /newhome/johndoe johndoe
    # Add a user to additional groups sudo usermod -aG sudo,developers johndoe
    # Change a user's login shell sudo usermod -s /bin/bash johndoe
    # Change a user's comment/GECOS field sudo usermod -c "John Doe - IT Department" johndoe
    # Advanced Examples Advanced
    # Lock a user account (prevent login) sudo usermod -L johndoe # Unlock a previously locked account sudo usermod -U johndoe # Change a user's login name sudo usermod -l newjohn johndoe # Change a user's UID sudo usermod -u 1500 johndoe # Change a user's primary group sudo usermod -g developers johndoe # Set account expiry date sudo usermod -e 2023-12-31 johndoe # Move home directory and update ownership sudo usermod -m -d /new/home/path johndoe # Change a user's login shell to prevent interactive login sudo usermod -s /sbin/nologin johndoe # Add a user to multiple groups in one command sudo usermod -aG docker,sudo,adm,www-data johndoe # Specify a custom SELinux user for the account sudo usermod -Z staff_u johndoe # Change password expiry information sudo usermod -f 30 johndoe

    Try It Yourself

    Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

    Understanding Syntax

    Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

    Notes

    The `usermod` command is a powerful system administration utility in Linux and Unix-like operating systems used to modify existing user account attributes. It allows system administrators to change various aspects of a user's account without having to delete and recreate the account. This command directly modifies the system account files such as `/etc/passwd`, `/etc/shadow`, and `/etc/group` to apply the requested changes. Because it modifies these critical system files, `usermod` typically requires root or sudo privileges to execute. **Key Features and Common Uses:** 1. **Group Management**: One of the most common uses of `usermod` is to modify a user's group memberships. The `-G` option specifies supplementary groups, but be careful as it replaces all existing supplementary groups. The `-a` (append) option in conjunction with `-G` allows adding to existing group memberships without removing current ones. 2. **Account Security**: The command provides options to lock (`-L`) and unlock (`-U`) user accounts by modifying the password hash in the shadow file. This is useful for temporarily disabling access without deleting the account. 3. **Account Expiration**: The `-e` option sets an expiration date for the account, after which the user will no longer be able to log in. This is particularly useful for temporary accounts. 4. **Login Shell**: The `-s` option changes a user's login shell. This can be used to grant or restrict shell access. Setting the shell to `/sbin/nologin` or `/bin/false` effectively prevents interactive logins. 5. **Home Directory Management**: The `-d` option changes the user's home directory path, and when combined with `-m`, it also moves the contents of the old home directory to the new location. 6. **User Identification**: Options like `-u` (change UID), `-g` (change primary group), and `-l` (change login name) allow for comprehensive identity management. **Important Considerations and Best Practices:** 1. **User Sessions**: Changes made with `usermod` generally don't affect currently active sessions. Users may need to log out and log back in for changes to take effect. 2. **Group Modifications**: When using `-G` without `-a`, all existing supplementary group memberships are replaced. This can inadvertently remove a user from important groups if not careful. 3. **Home Directory Changes**: When changing a home directory with `-d` but without `-m`, the user's files remain in the old location, which might cause confusion. 4. **UID/GID Changes**: Changing a user's UID with `-u` doesn't automatically update ownership of files owned by that user outside their home directory. Manual updating with commands like `find` and `chown` may be necessary. 5. **Account Locking**: The `-L` option only prevents password-based logins. Users might still be able to log in using SSH keys or other authentication methods. 6. **Backup Before Changes**: It's always good practice to backup system files like `/etc/passwd` and `/etc/shadow` before making significant changes with `usermod`. **Comparison with Other User Management Commands:** - **`useradd`**: Used to create new user accounts. - **`userdel`**: Used to delete user accounts. - **`passwd`**: Used specifically for changing user passwords. - **`chage`**: Used for detailed password aging and expiration management. The `usermod` command is essential for Linux system administrators as it provides a comprehensive way to manage user accounts after they've been created. Its wide range of options allows for precise control over user account attributes, making it a versatile tool for both day-to-day administration and implementing security policies.

    Related Commands

    These commands are frequently used alongside usermod or serve similar purposes:

    useradd
    userdel
    passwd
    chage
    groupmod
    Explore All Commands

    Use Cases

    Learn By Doing

    The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the usermod command works in different scenarios.

    See ExamplesTry Lab Exercises
    $ usermod
    View All Commands