$ Composer can't find mongodb extension, required Mongodb extension

$ Composer can't find mongodb extension, required Mongodb extension

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

Stefan Bogdanescu

Founder & Senior Architect

Composer Can't Find MongoDB Extension: Troubleshooting on macOS

When you attempt to run composer require mongodb/mongodb on a PHP 7.2 environment running on macOS, you will likely encounter a dependency resolution failure. The error output explicitly states that the requested PHP extension mongodb is missing from your system. While the screenshot provided in the source material shows an installation prompt in Xcode or Homebrew, this specific error usually indicates a mismatch between the installed library and the PHP interpreter's ability to load it.

The root cause here is almost never that you have failed to install the extension package itself. In fact, if you check your system images, you might see mongodb listed as installed via Homebrew (brew install mongodb). However, on macOS, installing a C-based library like MongoDB does not automatically compile and load the PHP module for the standard PHP installation provided by Apple or managed by Composer.

The core issue is that Composer resolves dependencies against the PHP CLI (Command Line Interface) version running in your terminal. When you run composer, it probes the currently active PHP binary (php) to see what extensions are loaded. If the ext-mongodb module is not compiled into that specific PHP binary or is not loaded via a .ini file, Composer will immediately reject any package requiring it, regardless of whether the system libraries exist elsewhere on the disk.

To resolve this on macOS with PHP 7.2, you must ensure the extension is explicitly enabled for the CLI environment. The most reliable method involves editing the php.ini configuration file associated with your active PHP installation. You can locate this file by running php -i | grep "Loaded Configuration File" in your terminal. Once you have identified the path, open the file and add or uncomment the line:

extension=mongodb.so

If the .so file does not exist in the expected directory (usually lib or extensions), you may need to run the Homebrew installation command with a specific flag to ensure it targets your local PHP, or use pecl install mongodb. Note that running pecl install requires the development headers for PHP 7.2 to be present and often requires Xcode Command Line Tools to be installed.

After modifying the configuration or installing via PECL, you must restart your terminal session or run a new shell to ensure the changes take effect, as some environments cache the loaded extensions. Then, verify the installation by running:

php -m | grep mongodb

If mongodb appears in the output, the extension is successfully loaded. You can now retry the Composer command:

composer require mongodb/mongodb

It is also worth noting that PHP 7.2 has reached its end of life. While this specific error is a configuration issue rather than a version incompatibility with the MongoDB driver itself (which supports older versions), relying on PHP 7.2 introduces security risks and limits access to newer Composer packages. If your project allows, upgrading to PHP 8.x or later is highly recommended, as modern PHP versions include more robust support for C extensions and better compatibility with the latest mongodb/mongodb driver releases.

If you are working within a Laravel ecosystem, this issue persists regardless of the framework version because it is fundamentally a PHP binary configuration problem. For developers managing multiple environments, ensure that your Docker or Vagrant configurations explicitly enable the ext-mongodb extension in the container image or virtual machine setup to prevent these errors from surfacing during deployment.

Our network