Comprehensive Guide to Resolving Homebrew Permission Issues

Problem Background and Symptom Analysis

Permission issues represent one of the most common obstacles when using Homebrew for package management on macOS systems. Users frequently encounter "Permission denied" errors during package installation or linking operations, typically resulting from improper filesystem permission configurations. Based on typical user scenarios, when attempting to install packages like libjpeg, the system displays linking failure error messages that clearly indicate permission denial when accessing critical directories.

Root Cause Investigation

The core of permission problems lies in the ownership configuration of Homebrew installation directories. In standard installations, the /usr/local directory should belong to the current user, but certain operations may alter this configuration. Common causes include: previous use of sudo commands for software installation leading to directory ownership changes, permission resets after system updates, or other software (such as Airfoil's InstantOn component) modifying directory permissions. The diagnostic output from the brew doctor command helps identify these issues, displaying warnings about unlinked kegs and configuration script conflicts.

Core Solution Approach

Based on community-verified best practices, the primary method for fixing permission issues involves using the chown command to reset directory ownership. The specific operation is as follows:

sudo chown -R "$USER":admin /usr/local

This command recursively changes the ownership of the /usr/local directory and all its subdirectories to the current user while maintaining admin group permissions. In some cases, the same operation needs to be performed on the cache directory:

sudo chown -R "$USER":admin /Library/Caches/Homebrew

Adaptation for Different System Versions

For macOS High Sierra and newer versions, due to system security restrictions, directly executing chown on /usr/local may not be feasible. In such cases, the Homebrew prefix path can be used:

sudo chown -R $(whoami) $(brew --prefix)/*

This approach obtains the actual installation path through brew --prefix, avoiding direct modification of system-level directories.

Special Handling for Cache Directories

When permission issues are concentrated in cache files, a more aggressive cleanup strategy can be employed:

sudo rm -rf ~/Library/Caches/Homebrew/
sudo chown -R {your username}:admin ~/Library/Caches/Homebrew/
sudo chmod -R 755 ~/Library/Caches/Homebrew/

This method first completely clears the cache, then re-establishes the correct permission structure.

Best Practices for Multi-User Environments

In systems requiring support for multiple users, simple ownership changes may not be the optimal solution. The correct approach involves adding users to the admin group:

sudo dseditgroup -o edit -a username -t user admin

This method maintains system multi-user compatibility while ensuring Homebrew-related directories remain accessible to all authorized users.

Verification and Testing

After completing permission restoration, the following commands should be run to verify the effectiveness of the solution:

brew doctor
brew link jpeg
brew install libjpeg

These commands respectively check system status, test linking functionality, and verify the installation process to ensure permission issues have been completely resolved.

Preventive Measures and Long-term Maintenance

To prevent recurrence of permission issues, it's recommended to: regularly run brew doctor to check system status; avoid unnecessary use of sudo in Homebrew operations; check critical directory permissions after system updates; establish monitoring mechanisms for permission changes. These measures effectively prevent similar problems and ensure long-term stability of the Homebrew environment.