How to install Supervisor on Ubuntu 24

Q: How do I install Supervisor on Ubuntu?

Run: sudo apt install supervisor Then add a .conf file for your program to /etc/supervisor/conf.d/ and load it: sudo supervisorctl reread && sudo supervisorctl update

Q: Do my programs start again after a reboot?

Yes, if the program has autostart=true (the default) and the supervisor service is enabled. The apt package enables it during installation.

To install Supervisor on Ubuntu you need one apt package, and then a small config file for each program it should keep running. Supervisor starts the program at boot, restarts it when it crashes and collects its output into logs. This guide is for Ubuntu 24.04 and 22.04 and uses a Laravel queue worker and a Node.js app as examples.

Install Supervisor on Ubuntu

sudo apt update
sudo apt install -y supervisor
sudo systemctl status supervisor --no-pager

Look for Active: active (running). The service is enabled and comes back after a reboot. Its main file is /etc/supervisor/supervisord.conf, and it reads every *.conf file in /etc/supervisor/conf.d/. That folder is where your programs go, one file each.

Add a Laravel queue worker

Laravel’s documentation runs queue:work under Supervisor so that workers come back after a crash or a deploy. Create the file:

sudo nano /etc/supervisor/conf.d/laravel-worker.conf

Paste this and change the path to your project and the user that owns it. Save with Control-O and exit with Control-X.

/etc/supervisor/conf.d/laravel-worker.conf

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/example.com/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/example.com/storage/logs/worker.log
stopwaitsecs=3600

numprocs=2: two workers run side by side, named laravel-worker_00 and laravel-worker_01.
user: the worker runs as this user, not as root. Use the one that owns the project files.
stopwaitsecs: how long Supervisor waits for the current job when it stops a worker. Make it longer than your longest job.
redirect_stderr and stdout_logfile: errors and output go into one log file.

Add a Node.js app

The same works for any program that runs in the foreground. For a Node.js app, create /etc/supervisor/conf.d/myapp.conf with this:

/etc/supervisor/conf.d/myapp.conf

[program:myapp]
command=/usr/bin/node server.js
directory=/var/www/myapp
user=www-data
autostart=true
autorestart=true
environment=NODE_ENV="production",PORT="3000"
redirect_stderr=true
stdout_logfile=/var/log/supervisor/myapp.log

Give the full path to node: Supervisor doesn’t read your ~/.bashrc. This shows it:

which node

Node.js from nvm lives in your home folder, which other users such as www-data can’t read on Ubuntu. Then set user to your own account, or use Node.js from NodeSource in /usr/bin.

Load the config with supervisorctl reread and update

Supervisor doesn’t notice new files by itself. reread reads the configs, update starts new programs and restarts the changed ones, status shows what runs:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

Each program must show RUNNING with a pid and its uptime. Run the same three commands after every change to a file in conf.d.

Everyday supervisorctl commands

Restart one program, for example after a deploy: sudo supervisorctl restart myapp restart doesn’t read changed config files, use update for that.
Restart all processes of a group: sudo supervisorctl restart "laravel-worker:*" The quotes keep the shell from expanding *.
Stop a program by hand: sudo supervisorctl stop myapp Start it again: sudo supervisorctl start myapp
Follow the program’s output live: sudo supervisorctl tail -f myapp Control-C stops it.
Logs: what you set in stdout_logfile, and Supervisor’s own log in /var/log/supervisor/supervisord.log.
Laravel after a deploy: php artisan queue:restart Workers finish the current job and exit, and Supervisor starts them again with the new code.

If supervisorctl or a program doesn’t start

unix:///var/run/supervisor.sock no such file: Supervisor itself isn’t running. Start it and turn it on at boot: sudo systemctl enable --now supervisor
error: <class 'PermissionError'>, [Errno 13] Permission denied: supervisorctl was run without sudo. Its socket is open to root only.
ERROR (no such process) or ERROR (no such group): Supervisor doesn’t know the name yet. Run reread and update, and check that the name matches the one in [program:…].
FATAL or BACKOFF with Exited too quickly (process log may have details): the command fails right away. Read the program’s log, or run the command by hand as the same user, for example: sudo -u www-data php /var/www/example.com/artisan queue:work
ERROR: CANT_REREAD: a mistake in a config file. The message names the file and the line.

If you also work on a Mac

MacWashing, System Junk: Xcode junk, user caches, installers and logs found, 22.83 GB ready to be cleaned

System Junk in MacWashing finds the caches of every app it knows, including those hidden inside app data, plus logs, Xcode junk and leftovers of deleted apps. It shows how much each takes and clears them in one go. Anything debatable stays unchecked until you decide.

Download MacWashing How it works

Free trial · macOS 14 or later

Questions and answers

How do I install Supervisor on Ubuntu?

Run: sudo apt install supervisor Then add a .conf file for your program to /etc/supervisor/conf.d/ and load it: sudo supervisorctl reread && sudo supervisorctl update

Do my programs start again after a reboot?

Yes, if the program has autostart=true (the default) and the supervisor service is enabled. The apt package enables it during installation.

Should I use Supervisor or systemd?

Both keep a program running. Supervisor is handy for groups of identical workers (numprocs) and is what Laravel’s documentation describes. A single service is just as easy to run as a systemd unit.