Composer "requires ext-X but it is missing" - Install PHP Extensions

A package declares a required PHP extension (e.g. ext-gd, ext-intl, ext-mbstring), and the PHP on the runner does not have it enabled. Composer refuses to install a set it knows would fail at runtime.

What this error means

composer install aborts during solving, naming a package that requires ext-X and noting it is missing from your system. The same composer.lock installs fine on a developer machine that has the extension.

composer output

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - intervention/image[3.0.0, ...] require ext-gd * -> it is missing from your
      system. Install or enable PHP's gd extension.

Common causes

The extension is not installed on the runner

A minimal PHP image ships only core extensions. Packages needing gd, intl, bcmath, zip, or mbstring then fail the platform check.

The extension is installed but not enabled

Some images ship the extension binary but do not load it. php -m does not list it, so Composer still treats it as missing.

How to fix it

Install the extension on the runner

On GitHub Actions, use shivammathur/setup-php to enable the extensions your packages need.

.github/workflows/ci.yml

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    extensions: gd, intl, mbstring, zip

Install it directly in a Docker image

Terminal

# Debian-based php image
apt-get update && apt-get install -y libpng-dev libjpeg-dev
docker-php-ext-configure gd --with-jpeg
docker-php-ext-install gd
php -m | grep gd

Bypass the check only when the runtime truly has it

If the build host genuinely cannot match the production extension set, you can skip the platform requirement - but install the extension where the code actually runs.