composer require laravel/horizon fails: ext-pcntl is missing
the requested PHP extension pcntl is missing from your systemShort answer
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension. pcntl is not enabled by default and does not work on Windows. Enable it for the PHP you run, build it into your Docker image, or run Horizon on Linux. Only skip the check on a machine that will not run Horizon.
Fix it fast
1Find out which cause you have
Ask the PHP that Composer uses whether pcntl is loaded. Composer checks that CLI, not the web server's PHP.
php -m | grep -i pcntl composer check-platform-reqs2Match what you see, then jump to its fix
- 1
php -m prints nothing for pcntl on Linux or macOS.PHP on this machine was built without pcntlFix - 2
composer install fails inside a php image build with the same missing extension message.The Docker image does not have pcntlFix - 3
php -m on Windows never lists pcntl.You are on Windows, where pcntl does not workFix
- 1
What does the error look like?
the requested PHP extension pcntl is missing from your systemlaravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Cause 1 of 3
PHP on this machine was built without pcntl
1Check
The PHP manual says process control is not enabled by default and has to be compiled in with --enable-pcntl for the CLI.
php -r "var_dump(extension_loaded('pcntl'));"2Fix
Use a PHP CLI that has pcntl. If you compile PHP yourself, add the configure option; with a packaged PHP, pick a build whose php -m lists pcntl. Then run the install again.
./configure --enable-pcntl3Verify
php -m lists pcntl, and the install completes.
php -m | grep -i pcntlConfirmed by php.net
Cause 2 of 3
The Docker image does not have pcntl
1Check
The php image ships a set of extensions and gives helper scripts to add others. php -m shows what the image has.
docker run --rm php:8.3-cli php -m | grep -i pcntl2Fix
Add the extension with the image's helper script in your Dockerfile, before composer install.
RUN docker-php-ext-install pcntl3Verify
Rebuild the image and list the modules.
docker run --rm my-image php -m | grep -i pcntlConfirmed by hub.docker.com
Cause 3 of 3
You are on Windows, where pcntl does not work
1Check
The PHP manual states that the module does not function on non-Unix platforms such as Windows, so no php.ini change can enable it.
php -r "echo PHP_OS_FAMILY;"2Fix
Run the project on a Unix-like system, such as Linux in Docker. If you only need to install packages on this machine and will never run Horizon there, tell Composer to ignore that one requirement.
composer install --ignore-platform-req=ext-pcntl3Verify
Composer completes the install. Horizon itself must still run on Linux.
composer check-platform-reqsConfirmed by getcomposer.org
How do I stop it coming back?
- Keep the production image and the CI image on the same PHP extensions as the server that will run Horizon.
- Use --ignore-platform-req for one named extension only, never --ignore-platform-reqs for everything.
- Run composer check-platform-reqs in CI to see missing extensions before deploy.
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:
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
- EZ EstimaterConstruction quoting and job tracking for contractors, on a Laravel and Firebase stack.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
Related fixes
Back end
php artisan serve starts but the app is not reachable, or the .env is ignored
Server stops right after start with a non-zero exit code when --port is given and the port is busy
php artisan serve listens on 127.0.0.1 port 8000 by default.
4 causes, each with a fixBack end
Guzzle or Http::get fails with cURL error 6 in Laravel
Illuminate\Http\Client\ConnectionException: cURL error 6: Could not resolve host
cURL error 6 means the machine running PHP could not turn the host name in the URL into an IP address.
3 causes, each with a fixBack end
Laravel cannot find the database host: getaddrinfo failed
SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for mysql failed
The message means PHP could not turn DB_HOST into an IP address.
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 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 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 fix