Maaz Zindani

Loading the index…

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

Laravel Excel: Class 'Maatwebsite\Excel\Excel' not found

ErrorClass 'Maatwebsite\Excel\Excel' not found

Short answer

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. Run composer show maatwebsite/excel, then check discovery and the facade name Maatwebsite\Excel\Facades\Excel.

  • Applies to maatwebsite/excel 3.1, PHP 8.3, Laravel 12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Composer whether the package is in this project at all.

    composer show maatwebsite/excel
  2. 2Match what you see, then jump to its fix

    1. 1composer show says the package is not found.The package is not installed, or its install failedFix
    2. 2The package is installed but the Excel alias or the provider is not available.The service provider or facade is not registeredFix
    3. 3Calls to Excel::load() or Excel::create(), or an import of the old class name.Code written for Laravel Excel 2.x is running on 3.xFix

What does the error look like?

  • Class 'Maatwebsite\Excel\Excel' not found
  • Class "Maatwebsite\Excel\Excel" not found

Cause 1 of 3

The package is not installed, or its install failed

1Check

Look for the package in composer.json and for an extension error in the last composer output. The package needs the zip, xml, gd2, iconv, simplexml, xmlreader and zlib PHP extensions, and missing ones can fail the install.

grep maatwebsite composer.json
php -m | grep -iE "zip|xml|gd|iconv|simplexml|xmlreader|zlib"

2Fix

Install any missing extension for your PHP, then require the package. The docs give the constraint ^3.1; if it fails on your PHP version, run the command without it.

composer require "maatwebsite/excel:^3.1"

3Verify

The package should now be listed with its version.

composer show maatwebsite/excel

Confirmed by docs.laravel-excel.com

Did this fix it?

Cause 2 of 3

The service provider or facade is not registered

1Check

In 3.x the provider Maatwebsite\Excel\ExcelServiceProvider and the Excel facade are found by package discovery. Discovery turns off if composer.json lists the package, or '*', under extra.laravel.dont-discover.

grep -n -A4 "dont-discover" composer.json

2Fix

Remove the package from dont-discover. If you must register by hand, add the provider to bootstrap/providers.php in current Laravel, or to the providers array of config/app.php in older versions, and add the alias.

// config/app.php (older layout)
'providers' => [
    Maatwebsite\Excel\ExcelServiceProvider::class,
],
'aliases' => [
    'Excel' => Maatwebsite\Excel\Facades\Excel::class,
],

3Verify

Publish the package config; it only works when the provider is loaded.

php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config

Confirmed by laravel.com

Did this fix it?

Cause 3 of 3

Code written for Laravel Excel 2.x is running on 3.x

1Check

Search the code base for the 2.x methods that 3.0 removed.

grep -rn "Excel::load\|Excel::create" app/

2Fix

Import the facade from its 3.x namespace and move to the replacements: Excel::import() for load, and Excel::download() or Excel::store() with an export class for create.

use Maatwebsite\Excel\Facades\Excel;

return Excel::download(new UsersExport, 'users.xlsx');

3Verify

Call the route and check the file downloads.

php artisan route:list

Confirmed by docs.laravel-excel.com

Did this fix it?

How do I stop it coming back?

  • Commit composer.lock and install from it in deploys so the same package version reaches the server.
  • Keep the required PHP extensions in composer.json so a missing one fails before deploy.
  • Use the facade import from the docs instead of typing class paths from old tutorials.

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 require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

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.