Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Composer cannot find the mongodb PHP extension that a package requires

Errormongodb/mongodb requires ext-mongodb ... it is missing from your system. Install or enable PHP's mongodb extension.

Short answer

Composer never installs PHP extensions. It checks that the PHP running the command already loads ext-mongodb, and stops when it does not. Install the extension, add extension=mongodb.so to the php.ini that the command line reads, then run composer show --platform to see it listed. Wrong version and platform-config cases have their own messages.

  • Applies to Composer 2, PHP 8.4, macOS, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Composer which platform packages it sees for the PHP it is using. If ext-mongodb is not in the list, the extension is not loaded for that PHP. The message in your error then tells you which cause below applies.

    composer show --platform | grep -i mongodb
    php -i | grep -i "loaded configuration file"
  2. 2Match what you see, then jump to its fix

    1. 1it is missing from your system. Install or enable PHP's mongodb extension.The extension is not installed for this PHPFix
    2. 2The site works with MongoDB in the browser, while composer install on the same machine still says it is missingThe extension is enabled for the web server but not for the command lineFix
    3. 3the ext-mongodb package is disabled by your platform configcomposer.json disables ext-mongodb in its platform configFix
    4. 4it has the wrong version installedThe installed extension is older than the package needsFix

What does the error look like?

  • mongodb/mongodb requires ext-mongodb ... it is missing from your system. Install or enable PHP's mongodb extension.
  • the ext-mongodb package is disabled by your platform config. Enable it again with "composer config platform.ext-mongodb --unset".
  • it has the wrong version installed

Cause 1 of 4

The extension is not installed for this PHP

1Check

The PHP manual describes the extension as separate software that is installed and then enabled in php.ini. If composer show --platform prints nothing for mongodb, neither step happened for this PHP.

php -m | grep -i mongodb
php -i | grep extension_dir

2Fix

Install the extension, then enable it. The manual now recommends PIE over PECL, and for macOS with Homebrew it shows a command from a separate tap.

# recommended
pie install mongodb/mongodb-extension

# or PECL (deprecated)
sudo pecl install mongodb

# macOS with Homebrew, for PHP 8.4
brew install shivammathur/extensions/mongodb@8.4

# php.ini
extension=mongodb.so

3Verify

Composer lists the extension, and PHP loads it.

composer show --platform | grep -i mongodb
php -m | grep -i mongodb

Confirmed by php.net

Did this fix it?

Cause 2 of 4

The extension is enabled for the web server but not for the command line

1Check

The manual notes that the command line and web SAPIs may use separate php.ini files. Composer runs on the command-line PHP, so it reads that file, which can be a different one.

php -i | grep -i "loaded configuration file"
php -i | grep -i "additional .ini files parsed"

2Fix

Add the extension line to the php.ini that the command-line PHP loads. Do this for each environment that runs the extension.

extension=mongodb.so

3Verify

Run the same Composer command again.

composer install

Confirmed by php.net

Did this fix it?

Cause 3 of 4

composer.json disables ext-mongodb in its platform config

1Check

Composer prints this message when the extension is loaded but the project's config.platform section switches the package off. Look for it in composer.json.

grep -n -A5 '"platform"' composer.json

2Fix

Remove the setting. The message itself names the command.

composer config platform.ext-mongodb --unset

3Verify

Run the install again. The extension is now taken from the real PHP.

composer install

Confirmed by github.com

Did this fix it?

Cause 4 of 4

The installed extension is older than the package needs

1Check

The extension is loaded, but its version does not satisfy the constraint on the package. Read the installed version from PHP and compare it with the constraint in the error.

composer show --platform | grep -i mongodb

2Fix

Install a newer extension build with the same tool you used the first time, then restart PHP-FPM or Apache if the web server also uses it.

pie install mongodb/mongodb-extension

3Verify

Composer now shows the new version.

composer show --platform | grep -i mongodb

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • List ext-mongodb in composer.json next to the package, so a missing extension fails early and on every machine.
  • Install extensions in your Dockerfile or provisioning script, not by hand on a laptop, so every environment gets the same version.
  • Run composer check-platform-reqs in CI. It checks that your PHP and extension versions match the platform requirements.
  • Avoid a config.platform entry for ext-mongodb. Faking a platform package stops Composer checking the real one, and the failure moves to runtime.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

CodeIgniter 4 cannot write its cache files

CodeIgniter\Cache\Exceptions\CacheException: Cache unable to write to /var/www/app/writable/cache/

CodeIgniter 4's file cache needs a cache directory that the web server can really write to.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.