Maaz Zindani

Loading the index…

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

composer require laravel/horizon fails: ext-pcntl is missing

Errorthe requested PHP extension pcntl is missing from your system

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

  • Applies to PHP 8.3, Composer 2, Laravel 12, Docker php image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1php -m prints nothing for pcntl on Linux or macOS.PHP on this machine was built without pcntlFix
    2. 2composer install fails inside a php image build with the same missing extension message.The Docker image does not have pcntlFix
    3. 3php -m on Windows never lists pcntl.You are on Windows, where pcntl does not workFix

What does the error look like?

  • the requested PHP extension pcntl is missing from your system
  • laravel/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-pcntl

3Verify

php -m lists pcntl, and the install completes.

php -m | grep -i pcntl

Confirmed by php.net

Did this fix it?

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 pcntl

2Fix

Add the extension with the image's helper script in your Dockerfile, before composer install.

RUN docker-php-ext-install pcntl

3Verify

Rebuild the image and list the modules.

docker run --rm my-image php -m | grep -i pcntl

Confirmed by hub.docker.com

Did this fix it?

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

3Verify

Composer completes the install. Horizon itself must still run on Linux.

composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

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:

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

Next step

Want this handled for good?

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