Supervisord is the server component of Supervisor, a process control system for Unix-like operating systems that starts long-running programs, keeps them running and restarts them when they exit unexpectedly. In services and processes it acts as a process supervisor: a parent process that owns a set of child programs, captures their output and exposes commands to start, stop and inspect them.
Supervisord is written in Python and configured with INI-style files. It is widely used to run queue workers, application servers and helper scripts on servers, and inside containers that must run more than one process, without writing custom init scripts for each program.
How Supervisord manages processes
Supervisord runs as a daemon and starts each configured program as its direct child process. Because it is the parent, it receives a signal from the kernel whenever a child exits, which lets it detect crashes immediately instead of polling. It then applies the program’s restart policy to decide whether to start it again.
Each program moves through defined states. Understanding them helps interpret status output and diagnose restart loops.
| State | Meaning | Typical next state |
|---|---|---|
| STOPPED | Not running, by request or never started | STARTING on a start command |
| STARTING | Launched, waiting for startsecs to pass | RUNNING or BACKOFF |
| RUNNING | Stayed up longer than startsecs | EXITED or STOPPING |
| BACKOFF | Exited too quickly, will retry | STARTING or FATAL |
| FATAL | Retries exhausted, will not restart | STARTING only after manual action |
| EXITED | Exited from RUNNING | STARTING if the restart policy allows |
The companion tool supervisorctl connects to Supervisord through a UNIX domain socket or an optional HTTP interface. Administrators use it to view status, start or stop programs, tail logs and reload configuration with the reread and update commands without restarting unrelated programs.
Key configuration options
Each supervised program is declared in a [program:name] section. A few options control almost all behavior, and choosing sensible values prevents most operational problems.
| Option | Typical value | Purpose |
|---|---|---|
| command | Full path to the executable and arguments | What to run, in the foreground |
| autorestart | true, false or unexpected | When to restart after an exit |
| startsecs | 1 to 10 seconds | How long a program must stay up to count as started |
| startretries | 3 by default | Quick failures tolerated before FATAL |
| stopsignal and stopwaitsecs | TERM and 10 seconds by default | Graceful shutdown before SIGKILL |
| numprocs | 1 to the number of CPU cores | Runs several identical worker copies |
| user | An unprivileged service account | Drops root privileges for the child |
| stdout_logfile | File path with rotation settings | Captures program output |
The most important rule is that supervised programs must run in the foreground. If a program daemonizes itself by forking into the background, Supervisord sees the original process exit, assumes a failure and starts another copy, which leads to duplicate processes or endless restarts.
Supervisord compared with other process supervisors
Supervisord is one of several tools that keep services alive. The main differences lie in where the tool runs, what it can manage and how deeply it integrates with the operating system.
| Tool | Scope | Strength | Limitation |
|---|---|---|---|
| Supervisord | User-level supervisor for any program | Simple configuration, process groups | Not an init system, no dependency graph |
| systemd | Init system and service manager | Dependencies, cgroups, socket activation | Linux-specific, more complex unit files |
| PM2 | Supervisor focused on Node.js | Cluster mode and zero-downtime reloads | Best suited to JavaScript runtimes |
| Monit | Monitoring with corrective actions | Checks ports, files and resource use | Restarts by command, not as parent process |
| runit or s6 | Minimal supervision suites | Very small and fast, used in containers | Fewer convenience features |
On modern Linux distributions, systemd already provides supervision through restart policies in unit files. Supervisord remains popular where teams want one portable configuration across distributions, need to manage many worker processes as a group, or run several processes inside a single container.
Typical uses and good practices
Supervisord is especially common in web application stacks. Typical programs include background job workers, WebSocket servers, scheduled task runners and application servers such as Gunicorn or PHP queue consumers.
- Group related programs with
[group:name]so that a deployment can restart all workers with one command. - Set stopwaitsecs longer than the longest job so workers finish current tasks during a graceful shutdown.
- Run programs as unprivileged users rather than as root.
- Restrict the control interface: keep the UNIX socket permissions tight and do not expose the HTTP interface publicly without authentication.
- Rotate logs with logfile size and backup count options to prevent disks from filling.
Supervisord itself must also be kept running. On most servers it is started by the system’s init system, typically a systemd service that launches Supervisord at boot, which creates a two-level chain of supervision.
Limitations and common pitfalls
Supervisord detects process exit, not process health. A program that hangs, deadlocks or stops answering requests remains in the RUNNING state, so a hung process needs separate health checks or a watchdog.
| Symptom | Likely cause | Fix |
|---|---|---|
| Program cycles into FATAL | Crash on startup or wrong path | Check stderr log and test the command manually |
| Duplicate processes appear | Program daemonizes itself | Use the program’s foreground option |
| Jobs cut off during deploys | stopwaitsecs too short | Increase it and handle SIGTERM gracefully |
| Environment variables missing | Supervisord does not load shell profiles | Set environment in the program section |
| Config changes ignored | Only reread without update | Run reread, then update |
Supervisord also offers no native dependency ordering beyond priority numbers. If a worker requires a database or another service to be ready, the program itself should retry connections gracefully rather than rely on start order.
Understanding it simply
Supervisord is a caretaker program that runs on a server and watches over other programs. When one of those programs stops unexpectedly, Supervisord notices and starts it again, usually within seconds.
It also keeps the output of each program in log files. Administrators get simple commands to start, stop and check everything it looks after. It works much like a night-shift supervisor who keeps a team working.
Applied in practice
An online shop sends order confirmations and generates invoices through a background job queue. The operations team defines a Supervisord program with numprocs set to four, so four worker processes consume jobs in parallel, each running as an unprivileged account with logs rotated at 50 MB.
One night a malformed order causes a worker to crash repeatedly. Supervisord restarts it each time, and the other three workers continue processing, so customers still receive confirmations. The team sets stopwaitsecs to 120 so that during deployments workers finish invoices in progress before stopping, which eliminates half-generated documents.