Maaz Zindani

Loading the index…

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

Composer says the gd extension is missing on a Laravel project

ErrorExtension gd is missing from your system

Short answer

Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension. Check what that binary has loaded with php -m, install or enable GD for that exact PHP, and run Composer again. Ignoring the check is only safe where GD is never used.

  • Applies to Composer 2.8, PHP 8.3, Laravel 12, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the PHP that Composer uses whether GD is loaded, and see which php.ini that PHP read.

    php -v
    php -m | grep -i gd
    php --ini
  2. 2Match what you see, then jump to its fix

    1. 1php -m prints no gd line on a Linux server.The GD package is not installed for this PHP versionFix
    2. 2php --ini shows a php.ini, and the line ;extension=gd is still commented.On Windows the extension line in php.ini is commented outFix
    3. 3The site shows GD working in phpinfo(), but composer still complains.Composer runs a different PHP than your web serverFix
    4. 4The error appears in a CI job or a Docker build stage that only installs dependencies.A build machine that never runs GD codeFix

What does the error look like?

  • Extension gd is missing from your system
  • composer install or composer update stops on a package that requires ext-gd

Cause 1 of 4

The GD package is not installed for this PHP version

1Check

List the PHP version first, because the extension package is versioned to it.

php -v
php --ri gd

2Fix

On Ubuntu 24.04 the package for PHP 8.3 is php8.3-gd. Install the one that matches your version, then restart the PHP service your site uses.

sudo apt install php8.3-gd
sudo systemctl restart php8.3-fpm

3Verify

GD should now show in the module list and Composer should resolve.

php -m | grep -i gd
composer install

Confirmed by packages.ubuntu.com

Did this fix it?

Cause 2 of 4

On Windows the extension line in php.ini is commented out

1Check

Open the php.ini that php --ini printed and look for the gd line.

php --ini
findstr /i "extension=gd" C:\php\php.ini

2Fix

Remove the leading semicolon so the line reads extension=gd. Make sure extension_dir points at the ext folder that holds the DLL. Before PHP 8.0 the DLL was called php_gd2.dll.

; php.ini
extension=gd

3Verify

Open a new terminal and list modules again.

php -m | findstr /i gd

Confirmed by php.net

Did this fix it?

Cause 3 of 4

Composer runs a different PHP than your web server

1Check

The web server and the CLI can be two PHP builds with two php.ini files. Composer only sees the CLI one.

which php
php --ini
composer check-platform-reqs

2Fix

Enable GD for the CLI PHP too, or call Composer through the PHP you meant. Use check-platform-reqs on the production machine to see every requirement that is not met, not just the first.

/usr/bin/php8.3 $(which composer) install

3Verify

check-platform-reqs should list ext-gd as success.

composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

Cause 4 of 4

A build machine that never runs GD code

1Check

Decide whether code on that machine really calls GD. If the image is only used to build assets or the vendor folder, the check does not protect anything there.

composer show --platform | grep -i gd

2Fix

Skip only that one requirement for that one command. Do not use the blanket ignore-platform-reqs flag, and keep the real runtime image on a PHP that has GD.

composer install --ignore-platform-req=ext-gd

3Verify

The install finishes; confirm the runtime image still passes check-platform-reqs.

composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

How do I stop it coming back?

  • List the PHP extensions your app needs in composer.json under require (ext-gd, ext-mbstring, ext-zip) so a missing one fails early.
  • Run composer check-platform-reqs in the deploy script on the real server.
  • Pin one PHP version across your laptop, CI and server so the extension set is the same.

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

Why a Filament panel feels slow on a Laravel server

The panel is fast on a small demo and slow once there are many resources, pages and widgets

A slow Filament panel on a server is most often running without the production caches.

3 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.