Maaz Zindani

Loading the index…

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

composer require maatwebsite/excel fails to install

Errorcomposer require maatwebsite/excel stops with a requirements error and the package is not added

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

  • Applies to Composer 2, Laravel 12, PHP 8.3, Laravel Excel 3.1
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/excel
  2. 2Match what you see, then jump to its fix

    1. 1Composer names a missing ext-zip, ext-gd or another ext- packageA required PHP extension is missingFix
    2. 2Composer says the package needs an older PHP version than yoursThe version constraint does not fit your PHPFix
    3. 3php -m shows the extension, but Composer still says it is missingComposer runs under a different PHP than the one you checkedFix

What does the error look like?

  • composer require maatwebsite/excel stops with a requirements error and the package is not added
  • Composer says the package needs an older PHP than the one installed
  • Composer 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/excel

3Verify

The require finishes and the package is in composer.json.

composer show maatwebsite/excel

Confirmed by docs.laravel-excel.com

Did this fix it?

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/excel

2Fix

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/excel

3Verify

Composer resolves and installs a version, and the autoloader is regenerated.

composer show maatwebsite/excel | head -n 5

Confirmed by docs.laravel-excel.com

Did this fix it?

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-reqs

2Fix

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/excel

3Verify

check-platform-reqs lists every requirement as success.

composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

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 fix

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.