Trouble with homebrew and libsodium

Trouble with homebrew and libsodium

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Trouble with Homebrew and Libsodium

When managing a development environment on macOS, it is common to maintain multiple PHP versions for different project requirements. A user running PHP 7.4, 8.0, 8.1, and 8.2 via Homebrew encountered a specific failure when executing Valet commands with PHP 7.4 active. The error message was straightforward but misleading:

dyld[68591]: Library not loaded: /usr/local/opt/libsodium/lib/libsodium.23.dylib

The dynamic loader reported that it could not find libsodium.23.dylib, even though a file named libsodium.26.dylib existed in the same directory. The immediate instinct is often to force the installation of an older version using a versioned formula, such as brew install libsodium@1.0.23. However, this command fails with a warning stating that no such formula exists.

This scenario highlights a fundamental misunderstanding regarding how Homebrew handles library naming conventions versus actual software versions. The confusion stems from the fact that the numeric suffix in the .dylib filename does not correspond to the semantic version of the Libsodium package itself. In this specific case, the file libsodium.26.dylib indicates that a newer build (likely corresponding to Homebrew formula version 1.0.26) is present on the system, but the application or PHP extension was compiled against an older specification expecting library version 23.

Since Libsodium 1.0.23 was never officially released by the maintainers, attempting to install it via brew is logically impossible. The Homebrew formula repository does not contain a versioned entry for a non-existent release. Therefore, trying to downgrade the formula to match the missing filename is not a viable solution.

The root cause of the error lies in how the PHP 7.4 installation was configured. When PHP extensions are compiled against external libraries like Libsodium, the linker records the specific library version it expects at build time. If PHP 7.4 was built when Libsodium 1.0.23 (or an earlier equivalent) was installed, the resulting binary will hardcode a dependency on libsodium.23.dylib. Subsequently upgrading Libsodium to a newer version (resulting in libsodium.26.dylib) leaves the older PHP binaries with broken dependencies.

To resolve this without breaking the existing setup, you must rebuild the PHP 7.4 installation or the specific extension linking against Libsodium. The most robust approach is to reinstall PHP 7.4 using Homebrew's PHP formula, ensuring it links against the currently installed version of Libsodium:

brew install php@7.4

After reinstallation, you may need to adjust your environment variables to ensure the correct PHP version is active when running Valet commands. You can verify the linked libraries by inspecting the binary with otool:

otool -L $(which php) | grep libsodium

This command will reveal exactly which .dylib file the current PHP executable is expecting. If it still references version 23 after a fresh install, you might need to force a relink of the specific extension or use brew unlink libsodium && brew link libsodium to ensure Homebrew's symlinks are consistent.

Alternatively, if you wish to keep the older Libsodium version specifically for compatibility with PHP 7.4, you would need to install that specific formula if Homebrew still supports it, though this is often discouraged due to security updates. A more modern approach is to update your PHP 7.4 installation to match the current Libsodium version, accepting that older PHP versions may eventually reach end-of-life and require migration paths similar to those suggested by LaravelCompany regarding Laravel ecosystem compatibility.

The key takeaway is that library filenames do not dictate version management strategies in Homebrew; the formula name does. Relying on filename matching leads to dead ends when trying to install non-existent versions. Correcting the build environment of the dependent application (PHP) rather than manipulating the library file names directly is the standard engineering practice for resolving dependency mismatches.

Our network