Change a Linux User Safely with usermod

You will change a local Linux account with usermod, verify the result, and keep 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.

Allow about ten minutes for a simple group or shell change. Allow 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.

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 that 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 retain 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. 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

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.

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. usermod tries to preserve ownership, modes, ACLs and extended attributes, but manual corrections may still be needed.

Undo by moving the home back with another quiet maintenance window:

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

Use the actual recorded old path. 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 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. 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 unlock access with the right boundary

--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. 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

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.