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.

Install

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

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"

Update

brew update

Usage

Managing packages

# Show installed packages
brew list -l

# Install a package
brew install {packageName}

# Show outdated packages
brew outdated

# Upgrade all packages
# WARNING — PROBABLY NEVER DO THIS. INSTANT REGRET.
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

Troubleshooting

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:
/usr/local/share/zsh
/usr/local/share/zsh/site-functions

And to fix it:

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

Reference

• Github: zsh-users/zsh-completions: issue 680
• Stack Overflow: zsh compinit insecure directories

Switch PHP version

You have to edit your .zshrc shell profile.

• GravDept Field Manuals: PHP
• Github: Homebrew/homebrew-core Issue #28102 Confused how to switch PHP version

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.

• Mark Shropshires: Reinstall Homebrew PHP after move from homebrew/php to homebrew/core
• Grav: macOS 10.13 High Sierra Apache Setup: Upgrading Homebrew

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).

Reference

• GitHub Gist — Vitor Britto: Remove MySQL completely
• GravDept Field Manuals — Valet+: Troubleshooting

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}