How can I solve "laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system"?

How can I solve "laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system"?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The ext-pcntl Dependency Wall in Laravel Horizon

When running composer install for a project involving Laravel Horizon, you may encounter an immediate blocker: laravel/horizon v1.1.0 requires ext-pcntl *. This error indicates that the PHP extension pcntl is not installed on your system. While this might seem like a simple missing package, resolving it requires understanding what pcntl actually does and why Horizon demands it specifically for process management tasks rather than standard web requests.

Laravel Horizon is designed to handle queue workers as long-running processes. Unlike typical PHP scripts that execute synchronously and terminate immediately after outputting a response, Horizon workers need to manage signals (like SIGTERM) to gracefully shut down when the server restarts or scales down. They also rely on process-specific mechanisms to monitor child processes and manage memory usage over extended periods. The pcntl extension provides the underlying PHP bindings for POSIX operating system functions related to process control, which are essential for these background tasks.

If you attempt to run Horizon without this extension, even if your queue workers start initially, they will fail to handle termination signals correctly. This can lead to orphaned processes that consume memory indefinitely or crash unexpectedly when the server receives a shutdown command. The error message explicitly points to C:\xampp-7.1\php\php.ini as a configuration file to check, but relying solely on .ini files is often insufficient if the extension isn't compiled into the PHP binary or enabled in the first place.

To resolve this issue, you must ensure that the pcntl extension is installed and active for your specific PHP installation. The exact method depends on your operating system. On Linux and macOS systems using standard package managers like apt, yum, or brew, you can install the extension via your package manager. For example, on Ubuntu, running sudo apt-get install php-pcntl followed by a reload of PHP-FPM or CLI will enable the extension.

In Windows environments, particularly with XAMPP as shown in your error log, the approach differs slightly. You need to locate the php.ini file corresponding to your CLI version of PHP (since Horizon workers usually run via CLI). Look for a line stating extension=pcntl.dll. If it is commented out with a semicolon, remove the semicolon to enable it. However, simply editing the config isn't enough if the DLL file isn't present in the ext directory. You may need to download the specific PCNTL extension DLL compatible with your PHP version and architecture (e.g., php-7.1) from a trusted repository or reinstalling the XAMPP package with an updated PHP version that includes this extension by default.

It is worth noting that some hosting providers disable pcntl for security reasons, as it allows processes to interact with the OS in ways that could potentially be exploited if misused. If you are deploying to a shared host or a restricted cloud environment, verify your hosting provider's policy before attempting to enable this extension. In such cases, you might need to downgrade Laravel Horizon to a version released prior to the ext-pcntl requirement or utilize an alternative queue management solution that does not rely on POSIX process control.

Always remember to restart your PHP server or CLI session after making changes to php.ini. For Docker-based setups, ensure that your Dockerfile includes the necessary compilation flags or installs the extension within the container image using the appropriate OS package manager commands. By addressing the missing extension and understanding the role of process control in background job processing, you can get Laravel Horizon up and running reliably without unexpected failures during scaling events.

Our network