Setting process priority for Laravel Horizon workers

Laravel Horizon lets you set the Linux nice value for worker processes, giving them more or less CPU scheduling priority.

Manoj Hortulanus 1 minute read Laravel
  1. Why you'd want this
  2. How to configure it
  3. Permissions
  4. Apply the changes
  5. Reverting

Why you'd want this

Linux schedules CPU time using a nice value between -20 (highest priority) and 19 (lowest). By default processes start at 0.

If your server is dedicated to queue processing or you're handling time-sensitive, CPU-intensive jobs, lowering the nice value gives workers a bigger slice of CPU time. On a shared server running web traffic alongside workers, you'd leave it at 0 or increase it to avoid starving your web processes.

How to configure it

Add a nice key to the supervisor block in config/horizon.php:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue'      => ['default'],
            'balance'    => 'auto',
            'processes'  => 20,
            'nice'       => -5,
        ],
    ],
],

Horizon calls PHP's proc_nice() when it starts each worker.

Permissions

Raising the nice value (e.g. 0 → 10) works for any user. Lowering it (e.g. 0 → -5) requires either root or the CAP_SYS_NICE capability. Without those privileges Horizon throws:

proc_nice(): Operation not permitted

To grant the capability to PHP without running as root:

sudo setcap cap_sys_nice=eip /usr/bin/php8.4

Verify it was applied:

getcap /usr/bin/php8.4
# /usr/bin/php8.4 cap_sys_nice=eip

Note: this grants the capability to the binary itself, so any PHP script running under that binary can adjust process priorities.

Apply the changes

php artisan config:clear
php artisan horizon:terminate

If Horizon is managed by Supervisor:

sudo supervisorctl restart horizon:*

Reverting

Remove the capability from the PHP binary:

sudo setcap -r /usr/bin/php8.4

No output from getcap afterwards means no capabilities are set. Also set 'nice' => 0 in config/horizon.php (or remove the key entirely) and restart Horizon.

For the broader picture of getting queues and the rest of the stack fast, see Laravel performance. Horizon needs Redis — if workers can't connect, see Redis connection refused.