Intervention/image · critical · MissingDependencyException

GD PHP extension must be installed to use this driver

Error message

GD PHP extension must be installed to use this driver

What it means

The GD driver's constructor runs checkHealth(), which verifies the gd extension is loaded and gd_info() exists, and throws MissingDependencyException otherwise. The library refuses to operate at all when its backend extension is unavailable.

Source

Thrown at src/Drivers/Gd/Driver.php:43

     *
     * @see DriverInterface::id()
     */
    public function id(): string
    {
        return 'GD';
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::checkHealth()
     *
     * @codeCoverageIgnore
     */
    public function checkHealth(): void
    {
        if (!extension_loaded('gd') || !function_exists('gd_info')) {
            throw new MissingDependencyException(
                'GD PHP extension must be installed to use this driver',
            );
        }
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::createImage()
     *
     * @throws InvalidArgumentException
     * @throws DriverException
     */
    public function createImage(int $width, int $height): ImageInterface
    {
        if ($width < 1 || $height < 1) {
            throw new InvalidArgumentException('Invalid image size. Must be int<1, max>');
        }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Install the extension: apt-get install php-gd, or docker-php-ext-install gd in Docker images, then restart PHP-FPM/worker
2. Enable extension=gd in php.ini (Windows: extension=php_gd.dll)
3. Verify in the exact failing SAPI: php -m | grep gd and php -r 'var_dump(gd_info());'
4. If GD cannot be installed, require ext-imagick and construct the manager with the Imagick driver

Example fix

// before
$manager = ImageManager::usingDriver(GdDriver::class); // fatal without ext-gd

// after (runtime check + fallback)
$driver = extension_loaded('gd') ? GdDriver::class : ImagickDriver::class;
$manager = ImageManager::usingDriver($driver);

// Dockerfile: RUN docker-php-ext-install gd

if (!extension_loaded('gd') || !function_exists('gd_info')) {
    throw new RuntimeException('Install ext-gd or configure the Imagick driver');
}
$manager = ImageManager::usingDriver(GdDriver::class);

function gdAvailable(): bool
{
    return extension_loaded('gd') && function_exists('gd_info');
}

try {
    $manager = ImageManager::usingDriver(GdDriver::class);
} catch (MissingDependencyException $e) {
    $manager = ImageManager::usingDriver(ImagickDriver::class);
}

When it happens

Trigger: Constructing ImageManager with the GD driver (new ImageManager(GdDriver::class) or ImageManager::usingDriver(...)) on PHP without ext-gd: slim Docker images, minimal distro installs, extension commented out in php.ini, CLI and web SAPIs using different ini files.

Common situations: php:8.x-cli Docker images ship without gd, Debian/Ubuntu needing the php-gd package, Windows php.ini without extension=gd, works locally but fails in CI or the production container because a different PHP binary is used.

Related errors

• Unable to read exif data
• Imagick PHP extension must be installed to use this driver
• Class '{objectShortname}' is not supported by {id} driver
• The specified position ({x}, {y}) is not within the image ar
• The specified index is outside of the range

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/3b10673ab6d63f3d. Report an issue: GitHub.