How to Use the diskutil resetUserPermissions Command in macOS Terminal to Repair Home Folder ACLs

In Apple macOS, user accounts rely on a complex permissions hierarchy that combines traditional Unix POSIX permissions (read, write, execute across User, Group, and Other) with Access Control Lists (ACLs) to manage access to personal directories, configuration plists, and application sandboxes. Over years of major macOS upgrades, Time Machine restores, manual command-line permission changes, or migrating profiles between Macs, these Access Control Lists inside the user’s home directory (/Users/username) can become malformed or corrupted. When this occurs, users experience bizarre operational symptoms: applications refuse to remember preferences, the Mac repeatedly asks for administrator passwords when saving files to the Desktop, or documents become permanently locked in “Read Only” mode. In macOS Terminal, Apple provides a native, low-level repair mechanism: the diskutil resetUserPermissions command.

Historically, older versions of Mac OS X featured a graphical “Repair Disk Permissions” button in Disk Utility; however, that legacy tool only checked system files, not home folders. In modern macOS versions—including macOS Sonoma and macOS Sequoia—the diskutil subsystem contains a specialised administrative verb specifically engineered to scan the user’s home container, purge orphaned ACL inheritance flags, and reinstate canonical ownership. This comprehensive guide outlines the architecture of macOS home folder permissions, demonstrates the exact command syntax for diskutil resetUserPermissions, explains how to determine your numeric User ID, and details post-repair verification steps.

Symptoms of Corrupted Home Folder Permissions on macOS

Before executing command-line repair utilities, verify whether your Mac exhibits common signs of home folder permission degradation:

Observed Issue / Symptom	Technical Root Cause	Resolution Delivered by diskutil
Finder Prompts for Password on File Moves	User account lacks write permissions or has an explicit “deny delete” ACL on Desktop/Documents.	Resets root folder ownership back to current user account.
Applications Fail to Save Preferences	The ~/Library/Preferences directory or container plist is owned by root instead of user.	Recursively restores read/write POSIX bits across all Library sub-hierarchies.
Downloads Locked as “Read Only”	Inherited Access Control Lists (ACLs) flag incoming web files with immutable attributes.	Strips invalid ACL entries while leaving standard file data intact.
Photos Library Refuses to Open	The Photos Library.photoslibrary package cannot acquire exclusive filesystem locks.	Rebuilds canonical user group permissions required for SQLite database locking.

Determining Your Target Volume and User ID (UID)

The diskutil resetUserPermissions command requires two specific parameters: the mount point of the startup volume (typically root /) and the numeric User Identifier (UID) of the target account. While the primary administrative user is almost always assigned UID 501, verifying your exact UID ensures you target the correct account.

Open Terminal (located in /Applications/Utilities/Terminal.app) and execute:

id -u

Terminal prints your active numeric UID:

501

To confirm your current short username and home directory path simultaneously:

echo "$USER : $HOME"

Executing diskutil resetUserPermissions in macOS Terminal

Once you have identified your UID, you can execute the reset command. Because the tool must inspect low-level filesystem descriptors and modify files across protected subdirectories, elevated superuser privileges via sudo are mandatory:

sudo diskutil resetUserPermissions / `id -u`

Tip: The backtick expression `id -u` automatically inserts your active numeric UID. If you prefer entering the number explicitly for user 501:

sudo diskutil resetUserPermissions / 501

When prompted, enter your macOS user login password (characters will not display on screen as you type) and press Enter.

Terminal will display progress output as it reconciles filesystem entries:

Ready to reset user permissions on disk3s1s1 (Macintosh HD) for UID 501
Started user permissions reset on disk3s1s1
[   ................................................. ]
Resetting permissions on user home directory (/Users/santh)...
Finished user permissions reset on disk3s1s1

Depending on the number of documents, photos, and development libraries stored inside your home directory, this operation typically takes between 30 seconds and two minutes. Once completed, Terminal returns you to the standard shell prompt.

Advanced Troubleshooting: Handling Error -69841

In certain enterprise environments or when repairing accounts that have experienced severe filesystem corruption, running diskutil resetUserPermissions directly within standard user space may terminate with error code -69841:

Error: -69841: Unable to reset permissions to the user home directory

This failure occurs when active background services or sandboxed system daemons maintain exclusive locks on files inside ~/Library/Containers. To resolve this error, execute the repair from macOS Recovery Mode:

1. Shut down your Mac completely.
2. Boot into Recovery:
   • Apple Silicon (M1/M2/M3/M4): Press and hold the power button until the screen displays “Loading startup options”, then select Options > Continue.
   • Intel Macs: Power on and immediately hold Cmd + R until the Apple logo appears.
3. If FileVault is enabled, select your administrator user and enter your password to unlock the encrypted APFS volume.
4. In the top menu bar, click Utilities > Terminal.
5. Run the repair command specifying the mounted volume path:

diskutil resetUserPermissions "/Volumes/Macintosh HD" 501

Because no third-party applications or user background daemons are running in Recovery Mode, the repair finishes cleanly without encountering file-locking errors.

Repairing ACLs Manually via the chmod Command

If specific desktop folders continue to exhibit inherited access restrictions, you can strip non-canonical Access Control Lists manually using the native Unix chmod command with the -N (remove ACL) and -R (recursive) flags:

chmod -R -N ~/Desktop ~/Downloads ~/Documents

To ensure that your user account has undisputed read and write ownership across all files inside your home folder:

chown -R $USER:staff ~

Restarting and Verifying File Permissions

Following the execution of diskutil resetUserPermissions, restart your Mac:

sudo reboot

Upon logging back in, test the resolution: create a new document on the Desktop, save a file from Safari into Downloads, and launch applications that previously exhibited configuration errors. All operations should execute smoothly without authentication dialogues or write-protection alerts.

By utilising the diskutil resetUserPermissions utility in macOS Terminal, administrators and power users can resolve frustrating permission deadlocks, eliminate spurious password prompts, and restore reliable filesystem operation.