Supervisor – A Process Management Tool in Python

Supervisor is a process control and management system which is very useful when running programs
on servers continuously. Supervisor is a client/server system that allows its users to monitor and control a number of processes on UNIX-like operating systems.

By the end of this tutorial you will learn

  • How to install and setup supervisor
  • How to use supervisor to run your programs and scripts
  • Differences between supervisord and supervisorctl
  • Configuring supervisor
  • Common Errors you may face when working with supervisor


  • supervisord
  • supervisorctl
  • conf file
  • Web UI

Installing Supervisor

Supervisor can be installed via apt or with pip python package manager as below

sudo apt-get install supervisor
pip install supervisor

Let us check the high level overview of Supervisor. This will help you to figure out
to fix errors you may face when working with supervisor.
Supervisor is a client/server system that allows its users to monitor and control a number of processes . Hence as a client/server system it consist of these two parts

The supervisord which starts,stops and manages all the processes. This act as the server
Supervisorctl which is a client CLI side for connecting to supervisord via either a unix socket hence the supervisor.sock you see or via an http/tcp socket.
Below is a brief diagram that shows the various components

How to use supervisor.

Supervisord requires a configuration file usually found in /etc/supervisor or /etc/supervisor/conf.d/ which is used to tell supervisord what to do and where to find what.
In order to use supervisor you will need this .conf file and then start the supervisord daemon either inside the directory with supervisor.conf or specify the conf file path to use via the -c command eg

# /etc/supervisor
# point to directory with supervisor.conf
supervisord  -c supervisor.conf

The resulting process will daemonize itself and detach from the terminal.
Supervisord will now start any program that was found in the .conf file

Where does supervisorctl comes to play?

As a client CLI to interface with supervisord, we can use supervisorctl to start,stop,restart,reread and check the status of a program on your supervisor.conf file. Anything under the program section can be managed using the supervisorctl CLI.

# check status of all programs
supervisorctl status all
# reread the supervisor.conf file if you made changes to it
supervisorctl reread
# reload the supervisor.conf file and restart programs
supervisorctl update
# start a program specified on supervisor.conf file
supervisorctl start myprogram

You can run this interactively if you dont specify an argument as below


Issues when working with supervisor

In order to fix the issues with working with supervisor you have to ensure that first you start the supervisord. This will create the sock file with the specifications in the conf file.
This avoids the error of file not found.

Sample Program

Below is a sample of a program in the [program] section of supervisor conf file.
The most important things include the following

  • command: this specifies the command or program you want to run. It is recommended to give the direct/absolute path to the program
  • directory: the directory your program is located
  • stdout_logfile and stderr_logfile: log files to keep track of logging
  • autostart, autorestart: specify if this program should automatically start or restart when down
  • startsecs
  • environments: environment variables that the above program may need or depends on

How to Use Supervisorctl Web UI

As we mentioned earlier, supervisorctl is a CLI to communicate with Supervisord via a unix socket. However
you can also communicate via TCP/HTTP socket using the inet_http_server section. This allows you to spin up a local Web UI by which you can do the same things with supervisorctl CLI.
Then you can navigate in your browser to localhost:9001 to see the Web UI

How to Stop or Start Supervisor Service

The basic workflow is this, Systemctl starts Supervisord when you start your Computer/Serve and then Supervisord will start the programs/process in the configuration file.

Hence to start or enable systemctl to start supervisord on PC/Server startup, you can enable it via the following

sudo systemctl enable supervisor
sudo systemctl start supervisor

The next time you start up your server/computer, it will be automatically started. However, if you want to stop or restart or check the status of supervisord you can use the following

sudo systemctl status supervisor
sudo systemctl stop supervisor
sudo systemctl restart supervisor

You can also check out the video tutorial below.
Thank you for your attention

  • Jesus Saves *
  • By Jesse E.Agbe(JCharis) *

Leave a Comment

Your email address will not be published. Required fields are marked *