How To Install and Manage Supervisor

In many VPS environments, you may have a number of small programs that you want to run persistently, whether these are small shell scripts, Node.js apps, or larger packages.

Usually, external packages are supplied with a unit file that allows them to be managed by an init system such as systemd, or packaged as Docker images that can be managed by a container engine. However, when software is not well packaged, or when you would prefer not to interact with a low-level init system on your server, it is helpful to have a lightweight alternative.

Supervisor is a process manager that provides a single interface for managing and monitoring a number of long-running programs. In this tutorial, you will install Supervisor and use it to define, start, and manage one or more programs from simple, per-program configuration files. You will also learn how Supervisor fits into modern Ubuntu and Debian systems (where it is typically managed by systemd), and you will get practical guidance for operating Supervisor-managed programs in real environments, including logging and rotation, security and permissions, best practices, and troubleshooting.

To complete this guide, you will need:

• An Ubuntu server and a non-root user with sudo privileges. You can learn more about how to set up a user with these privileges in our Initial Server Setup with Ubuntu guide.

Begin by updating your package sources and installing Supervisor:

sudo apt update && sudo apt install supervisor

The Supervisor service runs automatically after installation. You can check its status:

sudo systemctl status supervisor

You should receive the following output:

Output
● supervisor.service - Supervisor process control system for UNIX
     Loaded: loaded (/usr/lib/systemd/system/supervisor.service; enabled; preset: enabled)
     Active: active (running) since Wed 2026-02-25 06:46:51 UTC; 2h 50min ago
       Docs: http://supervisord.org
   Main PID: 3027 (supervisord)
      Tasks: 3 (limit: 4656)
     Memory: 20.4M (peak: 21.2M)
        CPU: 1min 18.224s

Now that we have Supervisor installed, we can look at adding our first programs.

Managing Supervisor with systemd

On modern Ubuntu and Debian systems, the Supervisor daemon (supervisord) is started and supervised by systemd. In practice, this means there are two layers of management, and it is important to use the right tool for the job.

• You use systemctl to manage the Supervisor service itself (for example, to start it, stop it, restart it, or enable it at boot).
• You use supervisorctl to manage the programs that Supervisor runs (for example, to reread configuration files, apply updates, start and stop a program, or view status).

As a rule, if you are troubleshooting whether Supervisor is running at all, use systemctl. If you are making changes to a single program definition under /etc/supervisor/conf.d/ or you want to control an individual supervised program, use supervisorctl.

For example, you can ensure Supervisor starts at boot with:

sudo systemctl enable supervisor

You can restart Supervisor after making changes to the main Supervisor configuration (for example, /etc/supervisor/supervisord.conf) with:

sudo systemctl restart supervisor

If you need to troubleshoot the Supervisor service itself, you can inspect its logs with journalctl:

sudo journalctl -u supervisor --no-pager -n 50

In contrast, if you are only changing a per-program configuration under /etc/supervisor/conf.d/, you will typically use sudo supervisorctl reread and sudo supervisorctl update to load those changes. This is usually preferable to restarting the entire Supervisor service, because restarting Supervisor can interrupt all programs that it is currently managing.

A best practice for working with Supervisor is to write a configuration file for every program it will handle.

To demonstrate Supervisor’s functionality, we’ll create a shell script that does nothing other than produce predictable output once a second, but runs continuously until it is manually stopped. Using nano or your favorite text editor, open a file called idle.sh in your home directory:

nano ~/idle.sh

Add the following contents:

#!/bin/bash
while true
do
  # Echo current date to stdout
  echo "$(date)"
  # Echo 'error!' to stderr
  echo 'error!' >&2
  sleep 1
done

Save and close the file. If you are using nano, press Ctrl+X, then when prompted, Y and Enter.

Next, make your script executable:

chmod +x ~/idle.sh

The per-program configuration files for Supervisor programs are located in the /etc/supervisor/conf.d directory. It is typical to run one program per file and to end each configuration file name with .conf. We’ll create a configuration file for this script as /etc/supervisor/conf.d/idle.conf:

sudo nano /etc/supervisor/conf.d/idle.conf

Add these contents:

[program:idle]
command=/home/<your_user>/idle.sh
autostart=true
autorestart=true
stderr_logfile=/var/log/idle.err.log
stdout_logfile=/var/log/idle.out.log

We’ll review this line by line:

command=/home/<your_user>/idle.sh

The configuration begins by defining a program with the name idle and the full path to the program. Replace <your_user> with your username.

The next two lines define the automatic behavior of the script under certain conditions.

autostart=true
autorestart=true

The autostart option tells Supervisor to start the program when the supervisord service starts (typically during system boot). Setting this to false will require a manual start following any system shutdown.

autorestart defines how Supervisor should manage the program in the event that it exits:

• false tells Supervisor not to ever restart the program after it exits.
• true tells Supervisor to always restart the program after it exits.
• unexpected tells Supervisor to only restart the program if it exits with an unexpected error code (by default anything other than codes 0 or 2). To learn more about exit codes, refer to your program’s documentation or the Linux exit status documentation.

The final two lines define the locations of the two main log files for the program.

stderr_logfile=/var/log/idle.err.log
stdout_logfile=/var/log/idle.out.log

As suggested by the option names, stdout and stderr will be directed to the stdout_logfile and stderr_logfile locations respectively. The specified directories must already exist, as Supervisor will not attempt to create any missing directories.

The configuration we have created here is a minimal template for a Supervisor program. The Supervisor documentation lists many more optional configuration options that are available to tune how programs are run.

Once our configuration file is created and saved, we can inform Supervisor of our new program through the supervisorctl command. First we tell Supervisor to look for any new or changed program configurations in the /etc/supervisor/conf.d directory with:

sudo supervisorctl reread

Output
idle: available

Followed by telling it to enact any changes with:

sudo supervisorctl update

Output
idle: added process group

Any time you make a change to any program configuration file, running the two previous commands will bring the changes into effect.

At this point our program should now be running. We can check its output by looking at the output log file:

sudo tail /var/log/idle.out.log

Output
Wed Feb 25 06:59:00 UTC 2026
Wed Feb 25 06:59:01 UTC 2026
Wed Feb 25 06:59:02 UTC 2026
Wed Feb 25 06:59:03 UTC 2026
Wed Feb 25 06:59:04 UTC 2026
Wed Feb 25 06:59:05 UTC 2026
Wed Feb 25 06:59:06 UTC 2026
Wed Feb 25 06:59:07 UTC 2026
Wed Feb 25 06:59:08 UTC 2026
Wed Feb 25 06:59:09 UTC 2026

Next, we’ll cover some other ways to use Supervisor.

Beyond running programs, you will want to stop, restart, or check their status. The supervisorctl program, which we used in Step 2, also has an interactive mode that you can use to control your programs.

To enter the interactive mode, run supervisorctl with no arguments:

sudo supervisorctl

Output
idle                      RUNNING    pid 12614, uptime 1:49:37
supervisor>

supervisorctl will initially print the status and uptime of all configured programs, followed by its command prompt. Entering help will reveal all of its available commands:

help

Output
default commands (type help <topic>):
=====================================
add    exit      open  reload  restart   start   tail
avail  fg        pid   remove  shutdown  status  update
clear  maintail  quit  reread  signal    stop    version

You can start or stop a program with the associated commands followed by the program name:

stop idle

Output
idle: stopped

start idle

Output
idle: started

Using the tail command, you can view the most recent entries in the stdout and stderr logs for your program:

tail idle

Output
Wed Feb 25 07:01:56 UTC 2026
Wed Feb 25 07:01:57 UTC 2026
Wed Feb 25 07:01:58 UTC 2026
Wed Feb 25 07:02:04 UTC 2026
Wed Feb 25 07:02:05 UTC 2026
Wed Feb 25 07:02:06 UTC 2026
Wed Feb 25 07:02:07 UTC 2026
Wed Feb 25 07:02:08 UTC 2026
Wed Feb 25 07:02:09 UTC 2026
Wed Feb 25 07:02:10 UTC 2026
Wed Feb 25 07:02:11 UTC 2026

tail idle stderr

Output
error!
error!
error!
error!
error!
error!
error!

Using status you can view again the current execution state of each program after making any changes:

status

Output
idle                             RUNNING   pid 3745, uptime 0:00:43

Finally, you can exit supervisorctl with Ctrl+C or by entering quit into the prompt:

quit

Supervisor can write a program’s standard output (stdout) and standard error (stderr) streams to dedicated log files (for example, by setting stdout_logfile and stderr_logfile in a program definition). This is often the simplest way to capture logs for scripts and small services, because you can keep each program’s output in predictable locations on disk.

When you configure file-based logging, keep two practical details in mind. First, the directories you reference must already exist, because Supervisor does not create missing directories for you. Second, the program must have permission to write to the log locations you specify. For example, if you write logs under /var/log/, you may need to create a dedicated subdirectory and ensure it is owned by the same user that runs the program.

For long-running services, it is also important to plan how those logs will be rotated so they do not grow without bounds and fill your disk.

Supervisor supports simple log rotation settings directly in each program definition. For example, you can add options like the following to control log size and how many rotated files are retained:

[program:idle]
command=/home/<your_user>/idle.sh
autostart=true
autorestart=true
stderr_logfile=/var/log/idle.err.log
stdout_logfile=/var/log/idle.out.log
stderr_logfile_maxbytes=10MB
stderr_logfile_backups=5
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5

In this example, Supervisor will rotate each log when it exceeds *_logfile_maxbytes, and it will retain up to *_logfile_backups older log files. These settings provide basic protection against unbounded log growth without requiring any additional tooling.

If you need more advanced log management (for example, compression, date-based rotation, or centralized policies across many services), you may prefer to use a system-level solution like logrotate or ship logs to a centralized logging system. In that case, it can still be useful to keep Supervisor writing to a stable location that your logging agent or rotation policy already monitors.

Supervisor is often used to keep application processes running, which means it is easy to accidentally grant those processes more access than they need. Before you deploy Supervisor-managed programs in production, it is worth reviewing a few practical security and permission considerations.

First, run your programs with the least privilege you can. If your program does not need root privileges, configure it to run as an unprivileged user by adding the user (and optionally group) setting to your program definition. For applications, it is often worth creating a dedicated service user (for example, with no interactive shell) so you do not accidentally run production processes as a personal login account.

[program:your_app]
command=/path/to/your/app
user=<your_user>

In addition to the user and group, you can further reduce risk by setting an explicit working directory and restricting default file permissions. This helps avoid surprises like programs writing files into root-owned directories or creating logs that are readable by unintended users:

[program:your_app]
command=/path/to/your/app
directory=/path/to/your/app
user=<your_user>
group=<your_group>
umask=027

Second, make sure your program can read and write only the files it needs. In practice, that usually means ensuring the application directory, any virtual environment, and any log directories are owned by the correct user and have appropriate permissions. If your program writes to log files (for example, under /var/log/), make sure the directory exists and is writable by the program user; otherwise, the program may fail to start or it may silently lose logs.

Third, treat Supervisor configuration files as sensitive operational configuration. Store them in root-owned locations like /etc/supervisor/conf.d/, keep permissions restrictive, and use sudo when editing them. Also be careful about secrets: Supervisor configs often include command-line arguments or environment variables (for example, database URLs, API keys, and credentials), so avoid making these files readable to non-administrators.

Finally, be cautious about exposing Supervisor control interfaces. Supervisor can be configured with HTTP control endpoints, but you should avoid binding any control interface to the public internet, because it can allow an attacker to start and stop processes or read operational information. If you enable remote control features for operational reasons, bind them to 127.0.0.1 or a private management network, require authentication, and restrict which users can access the control socket or endpoint. As a general rule, treat supervisorctl access as administrative access.

Supervisor and systemd can both keep services running, restart processes on failure, and start programs at boot. However, they solve different problems and they encourage different operational workflows.

In general, systemd is the default, first-choice service manager for modern Linux distributions. It is integrated deeply with the OS and is designed to manage system services consistently, with well-defined concepts for dependencies, ordering, resource limits, and structured logs.

Supervisor is a process control system that focuses on launching and monitoring one or more long-running programs from a simple, INI-style configuration. It is often useful when you want a lightweight, consistent interface for managing several small application processes (especially scripts and apps that do not ship a systemd unit file), or when you want the same program-management workflow across different projects.

It is also worth keeping in mind that on Ubuntu and Debian, Supervisor itself is typically started by systemd. In other words, you will often use systemctl to manage the Supervisor service, and supervisorctl to manage the programs that Supervisor runs.

The following comparison can help you decide which tool to use:

If you are managing a single well-packaged service, a native systemd unit is usually the simplest and most standard approach. It is also typically the better choice when you need service dependencies, strict ordering, OS-level hardening, or tight integration with distribution tooling.

If you are managing several small programs and you want a unified configuration and control interface, Supervisor can be a practical alternative. This is especially true when you need to supervise multiple application processes that are not packaged as services, or when you prefer a single tool (supervisorctl) for consistent start/stop/status and log tailing across all of your programs.

When configured thoughtfully, Supervisor can provide reliable and predictable process management for application workloads. However, many production issues arise from small configuration oversights. The following best practices will help you build a more secure, maintainable, and resilient Supervisor deployment.

Run Programs as a Non-Root User

By default, programs managed by Supervisor run with the same privileges as the supervisord service, which typically runs as the root user. Running application processes as root is rarely necessary and increases the potential impact of a security vulnerability or application bug.

In most cases, you should create and use a dedicated, least-privileged user for each application. You can enforce this in your program configuration by adding the user directive:

[program:myapp]
command=/usr/local/bin/myapp
user=myappuser
autostart=true
autorestart=true

Running processes with minimal privileges significantly reduces risk and aligns with standard Linux security practices.

Use Absolute Paths Consistently

Supervisor does not launch programs inside a full interactive shell environment. As a result, environment variables such as $PATH may not behave as you expect. Relative paths or implicit command resolution can therefore lead to subtle and difficult-to-debug failures.

To avoid these issues, you should always use absolute paths for:

• Executable commands
• Script arguments
• Working directories
• Log file locations

For example:

command=/usr/bin/python3 /opt/myapp/app.py
directory=/opt/myapp
stdout_logfile=/var/log/supervisor/myapp.out.log

Using explicit paths ensures consistent behavior across reboots, environments, and automation workflows.

Ensure Programs Run in the Foreground

Supervisor is designed to manage long-running foreground processes. If a program daemonizes itself (forks into the background), Supervisor may incorrectly interpret this as the program exiting and may repeatedly attempt to restart it.

Before adding any application to Supervisor, confirm that it runs in the foreground. Many server applications provide flags to disable daemon mode. When in doubt, consult the application’s documentation and explicitly disable backgrounding behavior.

As a general rule, if a program immediately returns control to the shell after starting, it is likely daemonizing and must be reconfigured.

Configure Automatic Restarts Thoughtfully

The autorestart setting is powerful but should be used carefully. While automatically restarting failed processes improves availability, an overly aggressive restart policy can mask underlying problems or create rapid crash loops that consume system resources.

For most production workloads, a balanced configuration is recommended:

autorestart=unexpected
startsecs=5
startretries=3

This approach tells Supervisor to restart the program only when it exits unexpectedly, to wait briefly before considering the start successful, and to avoid infinite restart attempts. Reserve autorestart=true for simple, well-understood worker processes that are expected to run continuously.

Keep Configuration Files Well Organized

As the number of managed programs grows, maintaining clear and consistent configuration files becomes increasingly important. Disorganized configurations make troubleshooting more difficult and increase the risk of operational mistakes.

You should adopt the following practices:

• Store one program definition per file
• Use descriptive filenames
• Follow consistent naming conventions
• Group related services logically

For example:

/etc/supervisor/conf.d/
├── web-api.conf
├── worker-default.conf
├── worker-priority.conf
└── scheduler.conf

A clean configuration structure will save time during debugging and future maintenance.

Manage Log Growth Proactively

Uncontrolled log growth is one of the most common operational problems in Supervisor deployments. Because Supervisor captures both stdout and stderr, log files can grow quickly, especially for verbose applications.

At minimum, you should enable Supervisor’s built-in log rotation:

stdout_logfile_maxbytes=50MB
stdout_logfile_backups=5
stderr_logfile_maxbytes=50MB
stderr_logfile_backups=5

This configuration limits individual log size and preserves a fixed number of rotated files. In larger environments, you may also consider integrating with the system logrotate utility or a centralized logging platform.

You should never allow Supervisor-managed logs to grow without bounds on a production system.

Validate Configurations Before Applying Changes

A small syntax error in a Supervisor configuration file can prevent a program from starting correctly. To avoid unexpected downtime, you should always validate and reload configurations in a controlled manner.

After modifying any program file, run:

sudo supervisorctl reread
sudo supervisorctl update

Then confirm the program status:

sudo supervisorctl status

This workflow helps you detect configuration problems early and ensures that changes are applied safely.

Tune startsecs for Slow-Starting Applications

Some applications require additional time to initialize before they are fully operational. If Supervisor checks the process too quickly, it may incorrectly mark the program as failed and attempt unnecessary restarts.

If your application has a noticeable startup time, increase the startsecs value:

startsecs=10

You should set this value slightly higher than the typical startup duration of your application. Proper tuning prevents false failure detection.

Use Supervisor for the Right Workloads

Although Supervisor is very capable, it is not intended to replace the system init system for core operating system services. Modern Linux distributions rely on systemd for low-level service orchestration, dependency management, and boot sequencing.

In general, you should prefer systemd for:

• Databases
• Networking services
• System daemons
• Boot-critical infrastructure

Supervisor is best suited for:

• Application workers
• Queue consumers
• Background jobs
• Multi-process application stacks

Using each tool for its intended purpose results in a cleaner and more maintainable architecture.

Monitor the Supervisor Service Itself

Finally, remember that Supervisor is itself a critical service. If the Supervisor daemon stops running, none of your managed programs will be restarted or monitored.

In production environments, you should:

• Ensure the Supervisor service is enabled at boot
• Include it in your monitoring and alerting systems
• Periodically review process status
• Investigate repeated restart events

A process manager is only effective if it remains healthy and continuously running.

Even when Supervisor is installed correctly, you may occasionally encounter issues when starting or managing programs. Most problems stem from small configuration mistakes, permission mismatches, or environment differences between your shell and Supervisor. The following guidance covers the most common failure scenarios and explains how to diagnose them methodically.

Supervisor Service Is Not Running

If the supervisorctl command reports connection errors or does not list any programs, the Supervisor daemon itself may not be running.

You should first verify the service status:

sudo systemctl status supervisor

If the service is inactive, start it with:

sudo systemctl start supervisor

If Supervisor fails to start or immediately exits, review the service logs to identify configuration errors or startup failures:

sudo journalctl -u supervisor --no-pager -n 50

In many cases, syntax errors in /etc/supervisor/supervisord.conf or invalid include paths prevent the service from starting successfully.

Program Shows as FATAL or BACKOFF

If Supervisor marks a program as FATAL or BACKOFF, it usually means the process is exiting too quickly after launch. Supervisor expects managed programs to remain running in the foreground, so rapid exits are treated as failures.

Common causes include an incorrect command path, missing executable permissions, the program daemonizing itself, missing runtime dependencies, or insufficient file permissions.

You should begin troubleshooting by running the command manually as the same user specified in the Supervisor configuration:

sudo -u <your_user> /full/path/to/program

If the program does not stay running in the foreground when started manually, Supervisor will not be able to manage it reliably.

You should also inspect the program logs using:

sudo supervisorctl tail <program_name>

The log output often reveals the exact reason for the failure.

Supervisor Cannot Write to Log Files

If a program fails immediately or produces no log output, the issue is often related to log file permissions or missing directories.

Remember that Supervisor does not create parent directories automatically. The directory specified in stdout_logfile and stderr_logfile must already exist, and the program’s configured user must have write access.

For example, if you intend to store logs under /var/log/, you should create and assign ownership appropriately:

sudo mkdir -p /var/log/supervisor
sudo chown <your_user>:<your_user> /var/log/supervisor

After correcting permissions, reload the program configuration and attempt to start the process again.

Configuration Changes Are Not Taking Effect

If you modify a file under /etc/supervisor/conf.d/ but do not observe any changes in program behavior, it is likely that Supervisor has not reloaded the updated configuration.

After editing any per-program configuration file, you should always run:

sudo supervisorctl reread
sudo supervisorctl update

The reread command instructs Supervisor to detect new or changed configuration files, and the update command applies those changes.

In most cases, you do not need to restart the entire Supervisor service when only per-program configurations have changed.

Program Runs Manually but Fails Under Supervisor

If your program runs successfully from the command line but fails when managed by Supervisor, the issue is usually caused by environmental differences.

Programs started by Supervisor do not inherit your interactive shell environment. As a result, failures commonly occur due to missing environment variables, incorrect working directories, PATH differences, or permission mismatches.

You can resolve many of these issues by explicitly defining the working directory in your program configuration:

directory=/path/to/your/app

If your application depends on environment variables, define them directly in the configuration:

environment=ENV_VAR="value",OTHER_VAR="value"

Being explicit about runtime context helps ensure consistent behavior between manual runs and Supervisor-managed execution.

Socket or Port Already in Use

If Supervisor repeatedly attempts to start a network service that binds to a port, the service may be failing because the port is already in use.

You can check which process is currently listening on a port with:

sudo ss -tulpn | grep <port>

If another instance of the application is already running outside Supervisor, stop it before allowing Supervisor to manage the service. Running duplicate instances of the same service often leads to confusing restart loops.

Excessive Rapid Restarts

If a program repeatedly crashes and restarts in quick succession, Supervisor may eventually mark it as FATAL after exhausting retry attempts. While you can make restart behavior more tolerant, frequent restarts usually indicate an underlying application problem that should be investigated.

For workloads that legitimately require more startup time, you can tune the following settings:

startsecs=5
startretries=3
autorestart=unexpected

However, you should avoid masking real application failures by simply increasing retry limits without understanding the root cause.

supervisorctl Cannot Connect to the Socket

If you encounter an error similar to:

unix:///var/run/supervisor.sock no such file

the Supervisor daemon may not be running, or the control socket may have incorrect permissions.

First, confirm that the Supervisor service is active:

sudo systemctl status supervisor

If the service is running, verify that the socket path configured in /etc/supervisor/supervisord.conf matches what supervisorctl expects. You should also ensure that the user running supervisorctl has permission to access the socket.

1. What is Supervisor used for on Ubuntu?

Supervisor is a process control system used on Ubuntu to manage and monitor long-running applications and background services. It allows you to automatically start programs, restart them if they crash, and manage multiple processes from a single interface. It is commonly used for application workers, queue consumers, and custom services that are not packaged as native systemd units.

2. How do I start Supervisor on Ubuntu?

On Ubuntu, Supervisor runs as a systemd service. You can start it by running:

sudo systemctl start supervisor

To ensure that Supervisor starts automatically at boot, enable the service with:

sudo systemctl enable --now supervisor

You can verify that it is running by checking its status with sudo systemctl status supervisor.

3. Where are Supervisor config files located?

On Ubuntu and Debian systems, the main Supervisor configuration file is located at:

/etc/supervisor/supervisord.conf

Per-program configuration files are typically stored in:

/etc/supervisor/conf.d/

It is considered best practice to create one .conf file per managed program in this directory.

4. How do I restart a process in Supervisor?

You can restart a managed program using the supervisorctl command. To restart a specific process, run:

sudo supervisorctl restart <program_name>

For example:

sudo supervisorctl restart idle

This command stops and then starts the program without requiring a full Supervisor service restart.

5. Does Supervisor start programs automatically?

Yes, Supervisor can start programs automatically if the autostart=true option is set in the program’s configuration. When this option is enabled, the program will start whenever the Supervisor daemon starts, which typically occurs at system boot if the Supervisor service is enabled. If autostart is set to false, you must start the program manually using supervisorctl start.

In this tutorial, you learned how to install and manage Supervisor to keep long-running programs running reliably. You created a per-program configuration file, applied changes with supervisorctl, and used Supervisor’s status and log tailing features to verify that your program was running correctly.

You also learned how Supervisor fits into modern Ubuntu systems where it is typically started and supervised by systemd, and when to use systemctl versus supervisorctl during day-to-day operations. Finally, you reviewed practical production considerations, including log configuration and rotation, security and permissions, and common best practices for organizing and operating Supervisor-managed services.

If you’re running multiple small apps that need to be web-accessible, you may also want to read about configuring Nginx as a reverse proxy, which is another fundamental component of small, reusable deployments.

For more Ubuntu-related tutorials, check out the following articles:

• Initial Server Setup with Ubuntu
• Set Up and Configure an Application Server on Ubuntu 24.04
• How to Install Node.js on Ubuntu
• How To Install Python 3 and Set Up a Programming Environment on an Ubuntu 20.04 Server
• How to Install and Configure Nginx on Ubuntu | Step-by-Step Guide