macOS runner: "dyld: Library not loaded ... image not found" in CI

By Kaveh Alemi·Latchkey

At launch the dynamic linker tried to load a dylib from a hard-coded path and could not find it. The dependency is missing on the runner, or it was installed at a different prefix than the one baked into the binary.

What this error means

Running a tool or test fails with "dyld: Library not loaded: /usr/local/opt/.../lib.dylib, Reason: image not found" and the process aborts before doing any work.

dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.74.dylib
  Referenced from: /usr/local/bin/some-tool
  Reason: image not found

Common causes

A dependency was upgraded or removed

The binary references a specific dylib version; a brew upgrade bumped the version or relocated it, so the exact path no longer exists.

A different Homebrew prefix than expected

Apple silicon uses /opt/homebrew while Intel uses /usr/local. A binary built for one prefix cannot find dylibs on the other.

How to fix it

Reinstall or relink the dependency

1. Identify the missing dylib from the dyld message.
2. Reinstall the formula that provides it so the path is restored.
3. Re-run the tool.

brew reinstall icu4c
brew link --overwrite icu4c

Point dyld at the right library path

When the library lives at a known location, set the fallback library path so dyld can find it.

export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix)/lib"
some-tool --version

How to prevent it

• Pin dependency versions so dylib paths stay stable.
• Account for /opt/homebrew vs /usr/local across architectures.
• Reinstall a formula after a dependency upgrade breaks its links.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions