Skip to content
shellmap

usermod — Modify a user account — username, home, shell, groups across all 5 shells

Equivalents in every shell

Bashunix
sudo usermod -aG docker alice

From `shadow-utils` (or `passwd` package). `-a -G <group>` is the most common form: ADD alice to the `docker` supplementary group (the `-a` is critical — without it, `-G` REPLACES the entire supplementary set, silently kicking the user out of every other group). Other common flags: `-s /bin/zsh` change login shell, `-d /new/home -m` change home dir and move contents, `-L` lock account, `-U` unlock, `-e 2026-12-31` set expiration.

Zshunix
sudo usermod -aG docker alice

Same Linux binary (`/usr/sbin/usermod`). NOT installed on macOS — macOS uses `dscl` (Directory Services CLI) for user/group operations. macOS equivalent of "add alice to docker group": `sudo dseditgroup -o edit -a alice -t user docker`. macOS equivalent of "change shell": `sudo chsh -s /bin/zsh alice` (which on macOS updates Open Directory, not `/etc/passwd`).

Fishunix
sudo usermod -aG docker alice

Same Linux external. Fish-specific reminder: the user's LOGIN SHELL setting in `/etc/passwd` is a SEPARATE concept from "fish is installed". To make fish the login shell after `apt install fish`, append it to `/etc/shells` first (`echo /usr/bin/fish | sudo tee -a /etc/shells`), then `sudo usermod -s /usr/bin/fish alice` (or `chsh -s /usr/bin/fish` as alice herself). Without the `/etc/shells` step, `usermod` refuses with "invalid shell".

PowerShellwindows
Set-LocalUser -Name alice -Description "Updated"

PowerShell's closest analogue is the `LocalAccounts` module (Windows 10 / Server 2016+). For ADD-TO-GROUP specifically: `Add-LocalGroupMember -Group Administrators -Member alice`. For REMOVE-FROM-GROUP: `Remove-LocalGroupMember -Group Administrators -Member alice`. For account-state changes: `Set-LocalUser -Name alice -PasswordNeverExpires $true` / `Enable-LocalUser -Name alice` / `Disable-LocalUser -Name alice` / `Rename-LocalUser -Name old -NewName new`. For domain users use the AD module: `Set-ADUser alice -Description "..."` / `Add-ADGroupMember Administrators -Members alice`.

cmd.exewindows
net user alice /comment:"Updated"

cmd.exe uses `net user` (local accounts) and `net localgroup` (group membership). Common patterns: `net user alice newpass` change password; `net user alice /active:no` disable account; `net user alice /active:yes` enable; `net user alice /expires:never`; `net localgroup Administrators alice /add` add to local Administrators; `net localgroup Administrators alice /delete` remove. For domain users: `net user alice /domain ...` queries AD; modifications use `dsmod user` (legacy) or pwsh `Set-ADUser` (modern).

Worked examples

Add user to a supplementary group

Bash
sudo usermod -aG docker alice
Zsh
sudo dseditgroup -o edit -a alice -t user docker
Fish
sudo usermod -aG docker alice
PowerShell
Add-LocalGroupMember -Group docker -Member alice
cmd.exe
net localgroup docker alice /add

Change the login shell

Bash
sudo usermod -s /bin/zsh alice
Zsh
sudo chsh -s /bin/zsh alice
Fish
sudo usermod -s /usr/bin/fish alice
PowerShell
Set-LocalUser -Name alice -Description "shell change does not apply on Windows"
cmd.exe
rem Windows has no per-user login shell concept

Lock / disable an account

Bash
sudo usermod -L alice
Zsh
sudo dscl . -create /Users/alice IsHidden 1
PowerShell
Disable-LocalUser -Name alice
cmd.exe
net user alice /active:no

Gotchas

  • The `-G` flag REPLACES the user's entire supplementary group set if used without `-a`. `usermod -G docker alice` removes alice from every group except `docker`. This is the #1 footgun of `usermod`. ALWAYS use `usermod -aG <group> alice` ("append, supplementary group"). For removal, `gpasswd -d alice docker` is the safer cousin (only touches that one group). To audit before running: `groups alice` then re-check after.
  • Changes from `usermod` only take effect on the user's NEXT login. Currently-open shells keep their original credentials. After `usermod -aG docker alice`, alice's current bash session still gets "permission denied" on the docker socket — she must log out and back in (or run `newgrp docker` to spawn a sub-shell with the new group). Same applies to shell changes (`-s`): existing sessions keep the old shell, only new logins use the new one.
  • On Linux, `usermod -d /new/home -m alice` MOVES the existing home directory contents — but only if alice has no running processes (`lsof` against the old path returns empty) and the new path doesn't already exist. If alice is logged in, the move fails with "user alice is currently used by process". Fix: `pkill -KILL -u alice` first (drastic — terminates every alice process including services), or do the move while alice is offline (e.g., from rescue mode / single-user mode).
  • macOS has NO `usermod` binary. Trying to follow Linux tutorials on macOS gives "usermod: command not found". The macOS equivalents are scattered across multiple tools: `dscl` (Directory Service CLI) for most attribute changes, `dseditgroup` for group membership, `chsh` for login shell, `passwd` for password. Many Linux features (locking accounts with `-L`, expiration with `-e`) don't map cleanly — use `dscl . -create /Users/alice IsHidden 1` or pwpolicy-based hiding instead.
  • Windows `net user` and `Set-LocalUser` only manage LOCAL accounts on the current machine. For DOMAIN accounts (AD-joined machines) those commands either query AD read-only (`net user alice /domain`) or fail outright (`Set-LocalUser alice` says "user not found"). Modifying domain users requires `Set-ADUser` / `Add-ADGroupMember` from the ActiveDirectory module on a machine with RSAT installed, or from a Domain Controller. The two systems are intentionally separate.

WSL & PowerShell Core notes

pwshNo portable cmdlet — Windows pwsh uses `LocalAccounts` / `ActiveDirectory` modules; Linux / macOS pwsh has nothing equivalent (the underlying system is /etc/passwd or Open Directory, both shell-tool territory). For portable user-management scripts, the practical pattern is detect-and-branch: `if ($IsWindows) { Add-LocalGroupMember -Group $g -Member $u } elseif ($IsLinux) { & sudo usermod -aG $g $u } elseif ($IsMacOS) { & sudo dseditgroup -o edit -a $u -t user $g }`. There is no shortcut.
WSLWSL maintains its own `/etc/passwd` and `/etc/group` SEPARATE from the Windows user database. `usermod` inside WSL modifies the WSL VM only — it does NOT change anything in Windows. To modify Windows-side users from WSL, `net.exe user` and `Add-LocalGroupMember` via `pwsh.exe -Command "..."` both work directly from WSL bash. Mixed environments: scripts that provision both the WSL user (`apt`/`adduser`) AND the Windows user (`net user`/`Add-LocalGroupMember`) need to run each command in the right context — they're two databases.

Common tasks using usermod

Related commands