Fix 'dyld: Library not loaded' Ruby error on macOS after update

The 30-second fix: reinstall the gem or app

This is the first thing to try if you're seeing dyld: Library not loaded after a macOS update. Nine times out of ten, you just need to reinstall the Ruby gem that's causing the problem.

Say you're running a Rails app and you get this:

dyld: Library not loaded: /usr/local/opt/readline/lib/libreadline.8.dylib
  Referenced from: /usr/local/bin/ruby

The culprit here is almost always a native extension gem (like mysql2, pg, nokogiri, or redcarpet) that was compiled against a library that got updated or moved. macOS updates love to replace system libraries and break those paths.

What to do:

1. Find the gem that's broken. Look at the missing library path in the error — it tells you what it's after.
2. Reinstall that gem: gem uninstall <gemname> then gem install <gemname>
3. If you're using Bundler, run bundle pristine — this recompiles all native extensions from scratch. That's often all you need.

This works because macOS update probably bumped readline, openssl, or libyaml, and the compiled extension is looking for the old path. Recompiling fixes the link.

When this doesn't work:

If the same error comes back after the reinstall, or if you see Library not loaded: /usr/local/opt/ruby referencing your Ruby binary itself, move to the next section.

The 5-minute fix: clean up Homebrew's Ruby

This is the real fix for most people. macOS ships with a system Ruby at /usr/bin/ruby, but Homebrew installs its own at /usr/local/bin/ruby. After a macOS update, Homebrew often gets out of sync — libraries get updated but the Ruby binary doesn't.

Step 1: Check what Ruby you're running

which ruby
ruby --version

If it points to /usr/local/bin/ruby (Homebrew), proceed. If it's /usr/bin/ruby, the system Ruby is fine — the issue is with your gems (try the 30-second fix above).

Step 2: Reinstall Homebrew's Ruby

brew reinstall ruby

Don't bother with brew update && brew upgrade — that rarely helps here. You need a straight reinstall to fix the broken symlinks Homebrew leaves behind after a macOS update.

Step 3: Update your PATH

After reinstalling, Homebrew will yell at you about a missing PATH entry. Run this:

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

(If you're on Bash, replace ~/.zshrc with ~/.bash_profile.)

Step 4: Reinstall all your gems

Now do a fresh install of everything:

gem install bundler
bundle install # if you have a Gemfile

This fixes the library path issue for good — at least until the next macOS update.

When this doesn't work:

If you're still getting the error, you probably have a deeper issue — multiple Ruby versions installed, or a version manager that's confused. Move to the advanced fix.

The 15+ minute fix: full Ruby environment rebuild

This is for when you've tried everything and the error still shows up — usually because you have multiple Ruby installs (Homebrew, rbenv, RVM, system) all fighting each other. I've fixed this on at least a dozen Macs after Monterey, Ventura, and Sonoma updates.

Step 1: Strip it all down

Uninstall every Ruby you can find. This is aggressive but necessary.

# Remove Homebrew Ruby
brew uninstall --ignore-dependencies ruby

# Remove rbenv and its rubies
rbenv uninstall <version>
brew uninstall rbenv ruby-build

# Remove RVM if installed
rvm implode

# Clean up leftover gem directories
rm -rf ~/.gem
rm -rf ~/.bundle

Don't touch /usr/bin/ruby — that's Apple's system Ruby and removing it can break macOS. Just don't use it for development.

Step 2: Install a version manager (rbenv is my pick)

Skip Homebrew's Ruby entirely. Use rbenv — it keeps everything isolated and doesn't fight with system libraries.

brew install rbenv ruby-build
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc

Step 3: Install your Ruby version

rbenv install 3.3.0  # or whatever version you need
rbenv global 3.3.0
ruby --version  # verify it points to rbenv's shim

Step 4: Install gems fresh

gem install bundler
bundle install

This rebuilds everything with the correct library paths tied to rbenv's Ruby, not Homebrew's. The dyld error will be gone.

One more pro tip:

If you're on an Apple Silicon Mac (M1/M2/M3), you might also see this error with Homebrew installed in /opt/homebrew instead of /usr/local. Adjust the paths accordingly — the same logic applies.

I've seen this exact error pattern after every major macOS update since Catalina. The root cause is always the same: macOS overwrites or moves shared libraries during the update, and your Ruby or its extensions are still pointing to the old location. Don't waste time debugging the dylib paths themselves — just recompile the Ruby or the gems. That's the fix.