Homebrew is a package manager for Mac, which installs useful things that Apple forgot.

When Homebrew self-updates it breaks something nearly every time and it’s infuriating. The only reason I use Homebrew is because Valet+ requires it.


1. Install Apple’s developer tools

Homebrew requires Apple’s Command Line Developer tools. When you update macOS, Apple screws this up every time. You’ll probably get this error:

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

See xcode-select to fix that.

2. Install Homebrew

Follow the Homebrew install instructions.

3. Update shell profile

Command line tools that were installed by Homebrew must be in your shell’s $PATH to execute. Add this to your shell profile:

# For Homebrew
export PATH="/usr/local/sbin:$PATH"

# Force MySQL 5.7 as the "mysql" version
export PATH="/usr/local/opt/mysql@5.7/bin:$PATH"


No sugar coating. I avoid this at all costs because Homebrew updates break things. I’ve lost several days fixing each episode.

Homebrew also self-updates when it feels like it, so whatever.

brew update


Managing packages

# Show installed packages
brew list -l

# Install a package
brew install {packageName}

# Show outdated packages
brew outdated

# Upgrade all packages
brew upgrade

# Upgrade a package
brew upgrade {packageName}

# Uninstall a package
brew uninstall {packageName}

# Show package info (like where it's installed)
brew info {packageName}

Cleaning up

# Remove all old packages
brew cleanup

# Remove all old packages (dry run)
brew cleanup -n

# Remove old symlinks
brew prune


Security warning after install

After installing on macOS 10.15 I got a warning every time the console opens:

zsh compinit: insecure directories, run compaudit for list.
Ignore insecure directories and continue [y] or abort compinit [n]?

Running compaudit returns:

There are insecure directories:

And to fix it:

cd /usr/local/share
chmod g-w zsh
cd /usr/local/share/zsh
chmod g-w site-functions


Switch PHP version

You have to edit your .zshrc shell profile.

Forcefuly remove old PHP versions

Updating the PHP package may not remove old php.ini files, which breaks things. You have to remove them manually.

Forcefully remove MySQL and reinstall

The gods seek amusement in your existence, and made Homebrew update to MySQL 8 while you still need MySQL 5.7. This is painful but fixable.

1. Open your terminal.

2. Use mysqldump to export + backup all your databases.

3. Check for MySQL processes with: ps -ax | grep mysql

4. Stop or kill any MySQL processes (note: they kept respawning for me, I skipped it).

5. Run commands in terminal:

# Remove MySQL via Homebrew
brew remove mysql
brew cleanup

# Remove files
sudo rm /usr/local/mysql
sudo rm -rf /usr/local/var/mysql
sudo rm -rf /usr/local/mysql*
sudo rm ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist
sudo rm -rf /Library/StartupItems/MySQLCOM
sudo rm -rf /Library/PreferencePanes/My*

# Unload previous MySQL auto-login
launchctl unload -w ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist

# Open the previous MySQL config
nano /etc/hostconfig

# Then delete the line: MYSQLCOM=-YES-

# Remove previous MySQL preferences
rm -rf ~/Library/PreferencePanes/My*
sudo rm -rf /Library/Receipts/mysql*
sudo rm -rf /Library/Receipts/MySQL*
sudo rm -rf /private/var/db/receipts/*mysql*

6. Restart your computer just to ensure any MySQL processes are killed.

7. Run mysql in terminal. It should fail if MySQL was removed successfully.

8. Remove and re-install Valet+ so it installs the correct MySQL 5.7.

9. Force your shell to use MySQL 5.7 (see section: “Install” step 3).


Fix unlinked packages

When installing a packages, Homebrow might be unable to create symlinks into /usr/local/sbin. This is required so packages are available in the shell’s PATH variable.

# Check which packages are not symlinked properly:
brew doctor

# Check if the `/usr/local/sbin` directory exists:
cd /usr/local/sbin

# If not, create the directory:
cd /usr/local
mkdir sbin

# Change permissions so the directory is writeable by the system:
sudo chown -R `whoami`:admin /usr/local/sbin

# Link the packages:
brew link {packageName}