How to fix Homebrew permission errors

Homebrew permission errors usually mean the current user cannot write one of the directories where Homebrew installs formulae, stages casks, or links files into its prefix. The failure often appears after an earlier command was run with sudo, after files were restored from backup, or after another tool changed ownership under /opt/homebrew or /usr/local.

Homebrew is designed so normal install, upgrade, link, cleanup, and cask operations run as the Homebrew user after the initial install. Fixing the error means identifying the unwritable Homebrew-managed paths and returning those paths to the current user, not making every system directory writable.

The focused repair starts with the permission-related brew doctor checks, then applies Homebrew's own ownership and write-bit fix only to the paths those checks report. Avoid sudo brew and avoid recursive ownership changes across /opt, /usr/local, or /Applications; those broad changes can weaken system, application, or third-party file boundaries.

Related: How to run brew doctor

Steps to fix Homebrew permission errors:

Run the focused Homebrew permission diagnostics.

$ brew doctor check_access_directories check_cask_staging_location
Warning: The following directories are not writable by your user:
/opt/homebrew/Cellar

You should change the ownership of these directories to your user.
  sudo chown -R user /opt/homebrew/Cellar

And make sure that your user has write permission.
  chmod u+w /opt/homebrew/Cellar

check_access_directories covers formula and prefix directories. check_cask_staging_location covers the Caskroom staging path used by Homebrew Cask.

Confirm the active Homebrew prefix before changing ownership.
```
$ brew --prefix
/opt/homebrew
```
Apple Silicon Macs normally use /opt/homebrew, Intel Macs normally use /usr/local, and Linux installs normally use /home/linuxbrew/.linuxbrew. Repair the prefix used by the failing brew command.
Related: How to find a Homebrew package prefix
Inspect the Homebrew paths named by the diagnostic warning.
```
$ ls -ld /opt/homebrew/Cellar
drwxr-xr-x  25 root  admin  800 Jul  7 09:10 /opt/homebrew/Cellar
```
An owner such as root on a Homebrew-managed writable directory explains why the current user cannot install, upgrade, link, or clean packages in that path.
Change ownership of only the reported Homebrew directories to the current user.
```
$ sudo chown -R "$(whoami)" /opt/homebrew/Cellar
```
Use the exact paths reported by brew doctor or by the failing Homebrew command. Do not run a broad command such as sudo chown -R "$(whoami)" /opt, sudo chown -R "$(whoami)" /usr/local, or sudo chown -R "$(whoami)" /Applications.
Restore the user write bit on the same directories.
```
$ chmod u+w /opt/homebrew/Cellar
```
If brew doctor lists more than one Homebrew directory, pass the same set of paths to chown and chmod. If a cask warning names /Applications instead of the Caskroom, choose a writable cask destination or fix the macOS application permission separately rather than changing ownership of /Applications.

Rerun the focused diagnostics.

$ brew doctor check_access_directories check_cask_staging_location
Your system is ready to brew.

Rerun the Homebrew operation that first failed.
```
$ brew link wget
Linking /opt/homebrew/Cellar/wget/1.25.0... 47 symlinks created.
```
Use the original install, upgrade, cleanup, link, or cask command in place of the sample brew link command. If the next failure names a formula conflict, tap trust, network error, missing dependency, or unsupported package, the permission repair is complete and the new message needs its own fix.