composer require maatwebsite/excel fails to install
composer require maatwebsite/excel stops with a requirements error and the package is not addedShort answer
Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need. Ask Composer why with prohibits, check the platform with check-platform-reqs, then install the missing extensions (zip, gd and others) or require a version that matches your PHP.
Fix it fast
1Find out which cause you have
Compare the real PHP platform with what your installed packages need, then ask Composer who blocks the package.
composer check-platform-reqs composer prohibits maatwebsite/excel2Match what you see, then jump to its fix
- 1
Composer names a missing ext-zip, ext-gd or another ext- packageA required PHP extension is missingFix - 2
Composer says the package needs an older PHP version than yoursThe version constraint does not fit your PHPFix - 3
php -m shows the extension, but Composer still says it is missingComposer runs under a different PHP than the one you checkedFix
- 1
What does the error look like?
composer require maatwebsite/excel stops with a requirements error and the package is not addedComposer says the package needs an older PHP than the one installedComposer names a missing PHP extension such as zip or gd
Cause 1 of 3
A required PHP extension is missing
1Check
The Laravel Excel docs list the extensions it needs: zip, xml, gd2, iconv, simplexml, xmlreader and zlib. Compare them with the extensions of the PHP that Composer uses.
php -m | grep -iE 'zip|xml|gd|iconv|simplexml|xmlreader|zlib'2Fix
Install the missing extensions for the PHP version you use, then run Composer again. Use your system's PHP package manager or your PHP installer to add them.
php -m | grep -iE 'zip|gd'
composer require maatwebsite/excel3Verify
The require finishes and the package is in composer.json.
composer show maatwebsite/excelConfirmed by docs.laravel-excel.com
Cause 2 of 3
The version constraint does not fit your PHP
1Check
The docs describe this: a pinned constraint such as ^3.1 can pick a release whose PHP range does not include your PHP, and Composer rejects it.
php -v
composer prohibits maatwebsite/excel2Fix
Run the plain require without the caret constraint, as the Laravel Excel docs suggest, so Composer picks a release that matches your PHP.
composer require maatwebsite/excel3Verify
Composer resolves and installs a version, and the autoloader is regenerated.
composer show maatwebsite/excel | head -n 5Confirmed by docs.laravel-excel.com
Cause 3 of 3
Composer runs under a different PHP than the one you checked
1Check
check-platform-reqs reports the real platform that this Composer run sees, ignoring any config.platform override, so run it with the same command you use to install.
composer check-platform-reqs2Fix
Install the extension for the PHP binary that Composer actually uses, or call Composer through the right PHP binary.
php8.3 $(which composer) require maatwebsite/excel3Verify
check-platform-reqs lists every requirement as success.
composer check-platform-reqsConfirmed by getcomposer.org
How do I stop it coming back?
- Run composer check-platform-reqs on the server before every deploy.
- Keep one PHP version per project and use the same one in CI, on the server and locally.
- Read composer prohibits output before reaching for --ignore-platform-reqs, which only hides the problem.
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
Laravel Excel: Class 'Maatwebsite\Excel\Excel' not found
Class "Maatwebsite\Excel\Excel" not found
Laravel Excel classes are missing when the package never installed, when its provider and facade were not registered, or when old 2.x code points at classes that 3.x replaced.
3 causes, each with a fixBack end
Composer says the gd extension is missing on a Laravel project
composer install or composer update stops on a package that requires ext-gd
Composer refuses to install a package that requires ext-gd when the PHP binary running Composer has no GD extension.
4 causes, each with a fixBack end
composer install says the lock file is not compatible and asks for update
Your lock file does not contain a compatible set of packages. Please run composer update.
composer install checked the locked packages against this machine's PHP and extensions and found a conflict.
3 causes, each with a fixBack end
composer require laravel/horizon fails: ext-pcntl is missing
laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.
3 causes, each with a fixBack end
composer require laravel/passport stops with 'requirements could not be resolved'
... but these were not loaded, likely because it conflicts with another require.
Composer found no Passport release that fits your project at once.
4 causes, each with a fixBack end
Composer says the root composer.json requires a PHP version your PHP does not satisfy
Your requirements could not be resolved to an installable set of packages.
Composer compares the php constraint in your composer.json, or in a package, with the PHP that runs Composer.
3 causes, each with a fix