Home / Alt manpages / usermod(8)

  • usermod(8)
  • Admin command
  • linux

Change a Linux User Safely with usermod

One careless usermod --groups run wipes every supplementary group the account had, because it replaces the whole list unless told otherwise. This guide changes a local account, verifies the result, and keeps an undo path for the changes that can disrupt a login. The examples match shadow-utils 4.13, provided here by Ubuntu package passwd 1:4.13+dfsg1-4ubuntu3.2.

The route

Jump straight to the step you need, or tick off Done means at the end.

Allow about ten minutes for a simple group or shell change, longer for a home-directory or UID migration. You need an administrator account with sudo, the target login name, and a maintenance window if the account is active. Most operations below need elevated privileges because they edit account databases.

Checkpoint

Write down the current values before changing anything. The account database is usually /etc/passwd, /etc/shadow, /etc/group and /etc/gshadow. Back up the relevant data through your normal system backup process before a migration.

1. Inspect the Account First

Use ordinary, read-only commands to establish the current login, IDs, groups, home and shell. Replace LOGIN with the real account name:

$ getent passwd LOGIN
LOGIN:x:1001:1001:Example User:/home/LOGIN:/bin/bash
$ id LOGIN
uid=1001(LOGIN) gid=1001(LOGIN) groups=1001(LOGIN),27(sudo)
$ getent group project
project:x:1050:other-user

The exact output is host-specific. Use getent rather than assuming local files are the only source: an installation may use directory services. The local manual says NIS changes must be made on the NIS server, and remote identity systems need their own administrative workflow.

On Linux, usermod checks whether a user is running processes when the login name, numeric ID or home directory is changed. Do not rely on that check as a substitute for planning. Find active processes and sessions, then stop or drain them through the service's normal procedure:

$ pgrep -a -u LOGIN
$ loginctl user-status LOGIN

If either command shows work that matters, stop here. Changing an active account can leave services, sessions, scheduled work or file ownership in an awkward state.

2. Add One Supplementary Group Without Losing Others

The most common trap is -G. It replaces the complete supplementary-group list. Add -a when the intention is to keep the existing memberships:

$ sudo usermod --append --groups project LOGIN
$ id LOGIN
uid=1001(LOGIN) gid=1001(LOGIN) groups=1001(LOGIN),27(sudo),1050(project)

The named group must already exist, and the group list is comma-separated with no whitespace. Without --append, this command would remove every supplementary group not named by --groups. That is a destructive configuration mistake, even though the command itself normally prints nothing.

To replace the list deliberately, record the old list and pass the full desired list:

$ sudo usermod --groups sudo,project LOGIN
$ id LOGIN

Removing one membership uses --remove with --groups:

$ sudo usermod --remove --groups project LOGIN
$ id LOGIN

Recovery

Undo an accidental add by removing that group. Undo a replacement by running --groups again with the complete list you recorded before the change. A running login may need to start a new session before programs see updated group membership.

3. Change the Login Shell

Set a shell only after checking that it exists and is suitable for the account:

$ command -v bash
/usr/bin/bash
$ sudo usermod --shell /usr/bin/bash LOGIN
$ getent passwd LOGIN
LOGIN:x:1001:1001:Example User:/home/LOGIN:/usr/bin/bash

usermod changes the shell field in the account record. It does not test whether the shell is a good fit for every service using the account. For a service account, a non-interactive shell may be intentional; do not change it just to make an interactive login easier.

Recovery

To undo this example, run the same command with the original shell, such as /usr/sbin/nologin. Confirm the original value from your recorded output rather than guessing.

4. Move a Home Directory Carefully

Changing the home path with --home changes the account record. Add --move-home when the contents should move as well:

$ sudo usermod --home /srv/home/LOGIN --move-home LOGIN
$ getent passwd LOGIN
LOGIN:x:1001:1001:Example User:/srv/home/LOGIN:/usr/bin/bash
$ sudo find /srv/home/LOGIN -maxdepth 1 -mindepth 1 -printf '%f\n' | sort

The destination is created if needed when the existing home can be moved. If the current home does not exist, the manual says the new home will not be created either. usermod tries to preserve ownership, modes, ACLs and extended attributes, but manual corrections may still be needed.

Warning

Do not use --move-home while the account is using files, and do not treat a successful exit as proof that every application path was updated. Check the destination, ownership and service configuration. Keep the old location available until the new login and dependent services work.

Recovery

Undo by moving the home back with another quiet maintenance window, using the actual recorded old path:

$ sudo usermod --home /home/LOGIN --move-home LOGIN

If a partial move or a full destination already exists, stop and inspect before retrying; blindly merging directories can overwrite or obscure files.

5. Change a UID Only With an Ownership Plan

A UID change affects file ownership, not just the number shown by id:

$ sudo usermod --uid 1101 LOGIN
$ id LOGIN
uid=1101(LOGIN) gid=1001(LOGIN) groups=1001(LOGIN),27(sudo)
$ sudo find /home/LOGIN -user 1101 -maxdepth 2 -print

usermod updates the user's mailbox and the files it owns inside the home directory. Files outside that home must be found and fixed manually. The group ownership of files outside the home also needs separate attention when changing the primary group with --gid. Do not use --non-unique casually: sharing a UID makes two login names access the same identity and permissions.

Before a UID change, inventory files on local filesystems according to your storage layout, record the old UID, and plan ownership changes for application data, backups, containers and scheduled jobs. Afterward, search for files still carrying the old numeric UID.

Recovery

Undo by assigning the recorded original UID, but only after checking that the original number is not now used by another account.

6. Lock or Restore Login Access

--lock places a ! before the encrypted password. It disables password authentication, but the manual distinguishes that from disabling the whole account. If the account must be disabled, set an expiration date as well:

$ sudo usermod --lock LOGIN
$ sudo passwd --status LOGIN
$ sudo usermod --expiredate 1 LOGIN

This is security-sensitive and may interrupt a service or emergency access path. Record the previous shadow status and expiration value before changing it.

Recovery

To restore password access, use --unlock; to remove the account expiration, use an empty expiration value where your shell can pass one safely, or apply the recorded policy value:

$ sudo usermod --unlock LOGIN
$ sudo usermod --expiredate '' LOGIN

Warning

Do not put a new password or an encrypted password on a command line. Process listings can expose it. Use the system's password tool and policy instead of usermod --password for an interactive password change.

7. Check the Result and Stop at the Boundary

usermod usually produces no success message, so verify the field you changed and inspect the surrounding services:

$ getent passwd LOGIN
$ id LOGIN
$ sudo find /home/LOGIN -maxdepth 2 -printf '%u:%g %p\n' | head
$ pgrep -a -u LOGIN

For a login, start a fresh session and check id again. For a moved home or UID, test the exact service account workflow. Remember that crontab files and at jobs may need their ownership changed manually. Do not edit /etc/passwd or /etc/shadow by hand to repair a failed change; stop, restore from the recorded values or backup, and investigate the specific error.

Done means

  • Recorded the baseline. You recorded the original account values and confirmed the target is not actively running important work.
  • Kept memberships intact. You used --append with --groups when adding a membership.
  • Treated it as a migration. You treated home and UID changes as migrations, with ownership and service checks.
  • Told lock and expiry apart. You distinguished a locked password from a fully expired account.
  • Verified and can undo. You verified the changed records and know the recorded command or values that undo the change.