Composer says the gd extension is missing on a Laravel project
Extension gd is missing from your systemShort 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.
Fix it fast
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 --ini2Match what you see, then jump to its fix
- 1
php -m prints no gd line on a Linux server.The GD package is not installed for this PHP versionFix - 2
php --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
The site shows GD working in phpinfo(), but composer still complains.Composer runs a different PHP than your web serverFix - 4
The error appears in a CI job or a Docker build stage that only installs dependencies.A build machine that never runs GD codeFix
- 1
What does the error look like?
Extension gd is missing from your systemcomposer 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 gd2Fix
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-fpm3Verify
GD should now show in the module list and Composer should resolve.
php -m | grep -i gd
composer installConfirmed by packages.ubuntu.com
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.ini2Fix
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=gd3Verify
Open a new terminal and list modules again.
php -m | findstr /i gdConfirmed by php.net
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-reqs2Fix
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) install3Verify
check-platform-reqs should list ext-gd as success.
composer check-platform-reqsConfirmed by getcomposer.org
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 gd2Fix
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-gd3Verify
The install finishes; confirm the runtime image still passes check-platform-reqs.
composer check-platform-reqsConfirmed by getcomposer.org
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
Composer refuses to install because a PHP extension is missing
The requested PHP extension bcmath * is missing from your system.
Composer checks the PHP that runs it, not the PHP your web server uses.
3 causes, each with a fixServers
Composer reports a different PHP version than php -v on Ubuntu
You are running 8.1.2.
Composer takes its PHP version from the interpreter that runs it, unless config.platform fakes one.
3 causes, each with a fixBack 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 fixBack end
Intervention Image will not save the file in a Laravel app
Can't write image data to path (/var/www/app/public/uploads/photo.jpg)
Intervention Image writes straight to a file path.
3 causes, each with a fixBack end
Laravel file upload returns 413 behind nginx
413 Content Too Large
A 413 means a limit refused the request body before Laravel could use it.
3 causes, each with a fixBack end
Laravel says the bootstrap/cache directory must be present and writable
The /var/www/app/bootstrap/cache directory must be present and writable.
Laravel writes its package manifest into bootstrap/cache and throws when that folder is missing or the current user cannot write to it.
2 causes, each with a fix