~/.linuxbrew or adjust the ownership of the default /usr/local prefix using the sudo chown command. This ensures your user account has the necessary read and write permissions for all Homebrew operations.
Understanding the Root Cause
When you run the Homebrew installer script on macOS or Linux, it defaults to installing into /usr/local. On most Unix-like systems, this directory is owned by root, meaning only the superuser can create or modify files within it. If your current user does not have sudo privileges configured correctly, or if the directory permissions are too restrictive, the shell will throw a Permission denied error during the setup process.
This issue is distinct from path configuration problems. While missing Homebrew from your $PATH results in commands not being found, permission errors stop the installation entirely before any binaries are created. It is crucial to distinguish between these two scenarios to apply the correct fix. For users who have successfully installed Homebrew but still face issues running commands, verifying your environment variables is essential.
Solution 1: Installing in a User Directory (Recommended)
The safest and most modern approach is to install Homebrew in a directory that belongs entirely to your user account. This avoids modifying system-wide directories and prevents future permission conflicts. On macOS, Homebrew now recommends installing in /opt/homebrew for Apple Silicon Macs, while Linux users should use ~/.linuxbrew.
To perform this installation, open your terminal and execute the following steps:
- Step 1: Ensure you do not have an existing partial installation. If previous attempts failed, remove any incomplete directories using
rm -rf ~/.linuxbreworrm -rf /opt/homebrewdepending on your platform. - Step 2: Run the official installation script with the
--prefixflag set to your home directory. For example, on Linux, you can usebash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -- --prefix=$HOME/.linuxbrew. - Step 3: Follow the on-screen instructions to add the Homebrew binary path to your shell profile. This step is critical for ensuring your system can locate the newly installed tools.
If you encounter difficulties configuring your shell environment after installation, refer to our guide on How to Add Homebrew to PATH in Your Shell Profile for detailed instructions on updating .bashrc or .zshrc.
Solution 2: Fixing Permissions for /usr/local
If you prefer to keep the default installation location at /usr/local, you must manually change the ownership of the directory to your current user. This method grants your account full control over the Homebrew tree without requiring sudo for every package update or installation.
Execute the following commands in your terminal. Note that you will need your user password for the sudo commands:
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/etc
sudo chown -R $(whoami) /usr/local/include
sudo chown -R $(whoami) /usr/local/lib
sudo chown -R $(whoami) /usr/local/opt
sudo chown -R $(whoami) /usr/local/sbin
sudo chown -R $(whoami) /usr/local/share
sudo chown -R $(whoami) /usr/local/var
sudo chown -R $(whoami) /usr/local/share/zsh
sudo chown -R $(whoami) /usr/local/share/doc
sudo chown -R $(whoami) /usr/local/share/info
sudo chown -R $(whoami) /usr/local/share/locale
sudo chown -R $(whoami) /usr/local/share/man
sudo chown -R $(whoami) /usr/local/share/nix
sudo chown -R $(whoami) /usr/local/share/pkgconfig
sudo chown -R $(whoami) /usr/local/share/zsh/site-functions
sudo chown -R $(whoami) /usr/local/FrameworksAfter running these commands, verify that the ownership has changed by listing the directory contents with ls -la /usr/local. Your username should appear as the owner. Once confirmed, you can re-run the Homebrew installation script. The script will detect that the directories exist and belong to you, completing the setup without further permission errors.
Verifying the Installation
Regardless of the method chosen, always verify that Homebrew is functioning correctly after resolving permission issues. Run brew doctor in your terminal. This command performs a series of diagnostic checks to ensure your environment is clean and ready for package management.
If brew doctor reports no warnings or errors, your installation is successful. You can now proceed to install packages using brew install. If you continue to see permission-related messages, double-check that your shell profile changes were saved and that you have restarted your terminal session to load the new environment variables.
Frequently Asked Questions
Why did I get a permission denied error when running brew update?
This happens if you installed Homebrew in a system-owned directory like /usr/local but did not change the file ownership to your user account. The update process requires writing to these directories, which fails if they remain locked by root. Use the chown commands listed above to fix this.
Can I ignore permission errors and force the installation?
No, forcing the installation using flags like --force will not bypass operating system security restrictions. Attempting to write to protected system directories without proper privileges will always result in failure. You must address the underlying permission structure before proceeding.
Does this issue affect Windows Subsystem for Linux (WSL)?
Yes, WSL environments often mirror Linux permission structures where /usr/local is restricted. The same solutions apply: either install to a user directory like ~/.linuxbrew or adjust ownership. However, be aware that file system performance in WSL may differ from native Linux installations.
What should I do if I already have conflicting software in /usr/local?
If other software occupies parts of /usr/local, changing ownership might break those applications. In such cases, installing Homebrew in a separate user directory like ~/.linuxbrew is the safer option. This isolates Homebrew packages from system-level software and prevents conflicts.
How do I check my current user permissions in the terminal?
You can check your current user identity by typing whoami. To see the owner of a specific directory, use ls -ld /path/to/directory. Comparing the output of these two commands helps identify if there is a mismatch between your user ID and the directory ownership.