Laravel Horizon

Monitor and manage Laravel Redis queues with Horizon’s beautiful dashboard. Covers installation, balance strategies, Supervisor setup, and notifications.

What is Horizon?

Laravel Horizon provides a beautiful dashboard and code-driven configuration for Laravel Redis queues. It lets you monitor job throughput, runtime, and failures in real time while managing all worker configuration in a single version-controlled file.

Horizon extends Laravel’s core queue system. Make sure you are familiar with Queues & Jobs before proceeding. A running Redis instance is also required.

Installation

Horizon requires Redis as the queue backend. Ensure QUEUE_CONNECTION=redis is set in your .env file. Horizon is not compatible with Redis Cluster at this time.

Install Horizon via Composer:

composer require laravel/horizon

Publish Horizon’s assets and configuration:

php artisan horizon:install

This generates config/horizon.php and app/Providers/HorizonServiceProvider.php.

Configuration

config/horizon.php overview

All worker configuration lives in config/horizon.php. The core option is environments, which defines worker process options per environment.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 60,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            'maxProcesses' => 3,
        ],
    ],
],

Horizon reserves the horizon Redis connection name internally. Do not assign this name to another connection in config/database.php.

Supervisors

Each environment can contain one or more supervisors. A supervisor manages a group of worker processes and handles balancing across queues. You can define multiple supervisors per environment to apply different strategies to different queues.

Default values

Use the defaults option to specify configuration values shared across all supervisors, reducing repetition.

'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'tries' => 1,
        'timeout' => 60,
        'maxProcesses' => 1,
    ],
],

Maintenance mode

When the application is in maintenance mode, Horizon stops processing jobs by default. To force processing, set force to true:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'force' => true,
        ],
    ],
],

Max job attempts

'environments' => [
    'production' => [
        'supervisor-1' => [
            'tries' => 10,
        ],
    ],
],

Setting tries to 0 allows unlimited attempts.

Job timeout

'environments' => [
    'production' => [
        'supervisor-1' => [
            'timeout' => 60,
        ],
    ],
],

The timeout value should always be at least a few seconds shorter than the retry_after value in config/queue.php. When using the auto balance strategy, Horizon force-kills workers that exceed the timeout during scale-down.

Job backoff

Specify how long Horizon waits before retrying a job that encountered an exception.

// Fixed delay
'backoff' => 10,

// Exponential backoff (1s, 5s, 10s, then 10s for subsequent retries)
'backoff' => [1, 5, 10],

Balancing strategies

Horizon offers three worker balancing strategies.

auto (default)

Automatically adjusts the number of worker processes per queue based on current workload. Configure the range with minProcesses and maxProcesses.

'supervisor-1' => [
    'balance' => 'auto',
    'autoScalingStrategy' => 'time', // or 'size'
    'minProcesses' => 1,
    'maxProcesses' => 10,
    'balanceMaxShift' => 1,
    'balanceCooldown' => 3,
],

• time — scales based on estimated time to clear the queue
• size — scales based on number of jobs in the queue

With auto balancing, queue order does not imply priority. Use multiple supervisors with explicit resource limits to enforce priorities.

simple

Distributes a fixed number of worker processes evenly across the specified queues.

'supervisor-1' => [
    'balance' => 'simple',
    'processes' => 10,
    'queue' => ['default', 'notifications'],
],

The example above assigns 5 processes to each queue.

false (no balancing)

Processes queues strictly in the listed order, similar to Laravel’s default queue system. Horizon still scales worker count as jobs accumulate.

'supervisor-1' => [
    'balance' => false,
    'queue' => ['default', 'notifications'],
    'minProcesses' => 1,
    'maxProcesses' => 10,
],

Jobs in default are always processed before notifications.

Dashboard authorization

The Horizon dashboard is accessible at /horizon. In local environments, it is open to everyone by default. In non-local environments, access is controlled by the authorization gate in app/Providers/HorizonServiceProvider.php.

use App\Models\User;
use Illuminate\Support\Facades\Gate;

protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            '[e-mail]',
        ]);
    });
}

If you secure Horizon via IP restrictions rather than authentication, make the user argument optional:

Gate::define('viewHorizon', function (User $user = null) {
    return true;
});

Running Horizon

Artisan commands

# Start Horizon
php artisan horizon

# Pause / resume all workers
php artisan horizon:pause
php artisan horizon:continue

# Pause / resume a specific supervisor
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# Check status
php artisan horizon:status
php artisan horizon:supervisor-status supervisor-1

# Gracefully terminate (waits for running jobs to finish)
php artisan horizon:terminate

Auto-restart during development

Use horizon:listen to automatically restart Horizon when files change.

npm install --save-dev chokidar
php artisan horizon:listen

# Inside Docker or Vagrant
php artisan horizon:listen --poll

Keeping Horizon running with Supervisor

In production, use Supervisor to ensure Horizon restarts automatically if it stops.

Install Supervisor

sudo apt-get install supervisor

Supervisor configuration

Create /etc/supervisor/conf.d/horizon.conf:

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600

Set stopwaitsecs to a value greater than your longest-running job’s duration. Otherwise Supervisor will kill the job before it finishes.

Start Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

On deployment

Terminate Horizon during each deployment so the process monitor restarts it with your new code:

php artisan horizon:terminate

With autostart=true and autorestart=true in the Supervisor config, Horizon will start back up automatically.

Managing jobs

Tags

Horizon automatically tags jobs based on the Eloquent models they receive.

// Dispatching with Video id=1 automatically adds the tag "App\Models\Video:1"
RenderVideo::dispatch(Video::find(1));

Define custom tags by implementing a tags() method on the job:

class RenderVideo implements ShouldQueue
{
    /**
     * @return array<int, string>
     */
    public function tags(): array
    {
        return ['render', 'video:'.$this->video->id];
    }
}

For queued event listeners, the event instance is automatically passed to tags():

class SendRenderNotifications implements ShouldQueue
{
    public function tags(VideoRendered $event): array
    {
        return ['video:'.$event->video->id];
    }
}

Silencing jobs

Hide specific jobs from the “Completed Jobs” list by adding them to the silenced option in config/horizon.php.

'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

// Silence by tag
'silenced_tags' => [
    'notifications',
],

Alternatively, implement the Silenced interface directly on the job class:

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;
    // ...
}

Metrics and monitoring

Horizon’s metrics dashboard shows job and queue throughput and wait times. Schedule the horizon:snapshot command to populate it.

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('horizon:snapshot')->everyFiveMinutes();

Clear all metric data with:

php artisan horizon:clear-metrics

Job failure notifications

Receive notifications when a queue’s wait time exceeds a threshold. Configure notification recipients in the boot() method of app/Providers/HorizonServiceProvider.php.

use Laravel\Horizon\Horizon;

public function boot(): void
{
    parent::boot();

    Horizon::routeMailNotificationsTo('[e-mail]');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#ops');
    Horizon::routeSmsNotificationsTo('15556667777');
}

Wait time thresholds

Configure how many seconds constitute a “long wait” in config/horizon.php:

'waits' => [
    'redis:critical' => 30,
    'redis:default' => 60,
    'redis:batch' => 120,
],

Setting a threshold to 0 disables notifications for that queue.

Managing failed jobs

Delete a specific failed job by ID or UUID:

php artisan horizon:forget 5

# Delete all failed jobs
php artisan horizon:forget --all

Clear all pending jobs from a queue:

# Clear the default queue
php artisan horizon:clear

# Clear a specific queue
php artisan horizon:clear --queue=emails

Upgrading Horizon

When upgrading to a new major version, review the Horizon upgrade guide carefully.

Related pages

Queues & Jobs

Laravel queue fundamentals: job creation, dispatch, batches, and failed job handling.

Redis

Configure and use Redis — the required backend for Horizon.