How to change user ID (UID/GID) on Linux & macOS

Category: Identity & PermissionsTools: usermod, groupmod, find, macOS dscl

When integrating workstations into NFS, LDAP, FreeIPA, or Active Directory environments, local numeric User Identifiers (UIDs) and Group Identifiers (GIDs) must match the directory server records. Mismatched IDs cause incorrect POSIX file ownership and broken access permissions across network-mounted filesystems.

Safety Prerequisites

Do not modify an active logged-in user: Log in as root or a separate administrative account.
Terminate all user processes: Stop background daemons and systemd user services running under the target UID.
Create a backup: Ensure files are backed up before updating filesystem ownership.

Method A: Linux (Ubuntu, Debian, Fedora, RHEL, Arch)

Example: Migrating user alice from old UID 1001 to new UID 2500 (and GID 1001 to 2500):

1. Terminate Running User Processes

sudo pkill -u alice
sudo loginctl terminate-user alice

2. Update Numeric UID and GID

# Change primary group GID
sudo groupmod -g 2500 alice

# Change user UID and assign new primary group
sudo usermod -u 2500 -g 2500 alice

3. Update File Ownership Across Filesystems

Update the user's home directory and scan local filesystems to reassign ownership of files previously owned by the old UID. The -xdev flag keeps the scan on local filesystems; entries in /etc/fstab that mount network shares will need ownership verified separately after the UID change.

# Update user home directory
sudo chown -R 2500:2500 /home/alice

# Scan local filesystems (using -xdev to stay within local mounts)
sudo find / -xdev -user 1001 -exec chown -h 2500 {} +
sudo find / -xdev -group 1001 -exec chgrp -h 2500 {} +

Method B: macOS (Sonoma, Sequoia, and Later)

On macOS, user account attributes are managed through OpenDirectory using the dscl utility.

1. Change the UID via dscl

# Change UniqueID from 501 to 2645
sudo dscl . -change /Users/alice UniqueID 501 2645

# Change PrimaryGroupID if required
sudo dscl . -change /Users/alice PrimaryGroupID 20 2645

# Flush local DirectoryService cache
sudo dscacheutil -flushcache

# On macOS 10.5+ (Leopard and later), caching is handled by opendirectoryd.
# Use odutil as the modern alternative:
sudo odutil reset cache

2. Update File Ownership on macOS

# Update home directory ownership
sudo chown -R 2645:2645 /Users/alice

# Update user library and application support files
sudo find /Users/alice -uid 501 -exec chown -h 2645 {} +
sudo find /Library -uid 501 -exec chown -h 2645 {} +

Sources & references

usermod(8) — Linux manual page — documents the usermod command, including the -u option to change UID and confirmation that file ownership must be fixed manually
groupmod(8) — Linux manual page — documents the groupmod command, including the -g option to change GID and manual file group ID updates
chown(1) — Linux manual page — documents the chown command, -h option for symbolic links, and -R for recursive changes
find(1) — Linux manual page — documents the find command, -user and -group predicates, and -exec for the find/chown ownership update pattern
loginctl(1) — Linux manual page — documents the loginctl terminate-user command for stopping systemd user services before UID changes
dscl(1) — macOS General Commands Manual — macOS dscl man page documenting the -change record_path key old_val new_val command for modifying UID/GID on Directory Service nodes

Frequently asked questions

How do I change a user UID on Linux?

Use `usermod -u NEWUID username` to change the UID and `groupmod -g NEWGID groupname` to change the primary GID. Then update file ownership with `find / -xdev -user OLDUID -exec chown -h NEWUID {} +`.

How do I change a user UID on macOS?

Use `dscl . -change /Users/username UniqueID OLD NEW` to change the UID and `dscl . -change /Users/username PrimaryGroupID OLD NEW` for the GID. Flush the cache with `dscacheutil -flushcache` or `odutil reset cache`.

How do I fix file ownership after changing a UID?

On Linux, run `find / -xdev -user OLDUID -exec chown -h NEWUID {} +` and `find / -xdev -group OLDGID -exec chgrp -h NEWGID {} +`. On macOS, scan `/Users/username` and `/Library` with `find ... -uid OLDUID -exec chown -h NEWUID {} +`.

Why do UIDs need to match across systems?

When integrating workstations into NFS, LDAP, FreeIPA, or Active Directory, local UIDs and GIDs must match the directory server records. Mismatched IDs cause incorrect POSIX file ownership and broken access permissions on network-mounted filesystems.

Can I change the UID of a logged-in user?

No. Log in as `root` or a separate administrative account, not the target user. Stop all background daemons and systemd user services running under the target UID before making changes.

How do I stop user processes before changing a UID?

Run `sudo pkill -u username` to kill user processes and `sudo loginctl terminate-user username` to stop systemd user services for that account.

How do I flush the directory service cache on macOS after changing a UID?

Run `sudo dscacheutil -flushcache`. On macOS 10.5 (Leopard) and later, caching is handled by opendirectoryd, so use `sudo odutil reset cache` as the modern alternative.