usermod changes existing user accounts: their groups, login shell, home directory, name, UID and lock status. It needs root, and one flag in particular (-G without -a) has locked many admins out of sudo.

sudo usermod [options] USERNAME

Add a user to groups (the right way)

sudo usermod -aG sudo alice              # grant sudo (Debian/Ubuntu)
sudo usermod -aG wheel alice             # grant sudo (RHEL family)
sudo usermod -aG docker,www-data alice   # several groups, comma-separated, no spaces
  • -G sets supplementary groups.
  • -a appends instead of replacing.

Without -a, usermod -G docker alice makes docker alice’s only supplementary group, removing her from sudo and everything else. If you do this to your own account on a server without a root password, you can lose admin access. Always use -aG, and check with id alice afterwards.

The change applies at the user’s next login. See Linux groups.

Change the primary group

sudo usermod -g developers alice

New files will belong to developers. Existing files keep their group. Files in her home directory are updated automatically.

Change the login shell

sudo usermod -s /bin/bash alice
sudo usermod -s /usr/sbin/nologin svcuser    # disable interactive login (service accounts)

Users can change their own shell with chsh -s /bin/zsh. Valid shells are listed in /etc/shells.

Change the home directory

sudo usermod -d /home/newhome -m alice

-m moves the contents of the old home to the new location. Without -m, only the setting changes and the files stay behind.

Rename a user

sudo usermod -l newname oldname
sudo usermod -d /home/newname -m newname       # also move the home directory
sudo groupmod -n newname oldname               # rename the matching primary group

The user must not be logged in or running processes. Check with ps -u oldname. After renaming, update anything that refers to the old name: sudoers entries, cron, systemd units, SSH AllowUsers and file paths in configs.

Change UID or GID

sudo usermod -u 1500 alice
sudo groupmod -g 1500 alice

Files in alice’s home directory are updated to the new UID. Files elsewhere keep the old number, so fix them:

sudo find / -xdev -user 1001 -exec chown -h alice {} +
sudo find / -xdev -group 1001 -exec chgrp -h alice {} +

Matching UIDs matter for NFS shares and Docker bind mounts, where ownership is compared by number.

Lock and unlock accounts

sudo usermod -L alice     # lock password login (adds ! to the hash)
sudo usermod -U alice     # unlock

Locking the password doesn’t block SSH key logins. To fully disable an account:

sudo usermod -L -e 1 alice              # lock and expire the account
# or
sudo usermod -s /usr/sbin/nologin alice

An expired account (-e 1 sets the expiry to 1970-01-02) can’t log in by any method, keys included.

Account expiry

sudo usermod -e 2026-12-31 contractor   # account expires on this date
sudo usermod -e '' contractor           # remove the expiry
sudo chage -l contractor                # show expiry and password ageing

That’s useful for temporary accounts: contractors, auditors and support access. See passwd and chage.

Comment (full name)

sudo usermod -c "Alice Smith, Ops" alice

Common errors

usermod: user alice is currently used by process 1234 — you’re trying to rename the user or change the UID while they have running processes. Log them out (sudo pkill -u alice) or stop their services first.

usermod: group 'x' does not exist — create it with groupadd first.

Changes “don’t work” — group changes need a new login. The user should log out and back in, or run newgrp.

Locked yourself out of sudo?

If you ran usermod -G without -a on your admin account:

  • If another sudo-capable user exists, use it to run usermod -aG sudo you.
  • If root has a password, su - and fix it.
  • Otherwise, use your provider’s VNC console to boot into recovery or single-user mode, remount the root filesystem read-write and fix /etc/group. VPS.DO plans include console access in the control panel for this kind of rescue.

Quick reference

Task Command
Add to group usermod -aG group user
Primary group usermod -g group user
Shell usermod -s /bin/bash user
Move home usermod -d /new -m user
Rename usermod -l new old
Lock / unlock usermod -L / -U
Expire account usermod -e YYYY-MM-DD user
Change UID usermod -u 1500 user

Related: useradd and sudo.

  • Linux
  • Users
  • Security