Registry / devops / supervisor

supervisor

JSON →
library4.3.0pypypi✓ verified 24d ago

Supervisor is a client/server system that allows users to monitor and control a number of processes on UNIX-like operating systems. The Python package installs the `supervisord` server, `supervisorctl` client, and utilities. It also enables programmatic interaction with `supervisord` via its XML-RPC interface. The current stable version is 4.3.0, with releases occurring a few times a year for maintenance and feature updates.

pip install supervisor
INSTALL
IMPORT
SIG · SUPERVISOR
S
supervisor
devopspythonv4.3.0
Install
1.9s avg
Import
266ms
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.276s · 20.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.9s · import 0.256s · 21MB
19MB installed
● package 19MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

childutils
from supervisor import childutils
For utilities to interact with Supervisor from a supervised child process, e.g., for event listening.
ServerProxy
from xmlrpc.client import ServerProxy
Standard Python XML-RPC client for external control of the running 'supervisord' instance. The 'supervisor' package itself doesn't export a direct client class.

This quickstart demonstrates how to connect to a running `supervisord` instance using the standard Python `xmlrpc.client` and retrieve process information. It requires `supervisord` to be configured with an XML-RPC interface (e.g., `inet_http_server` in `supervisord.conf`) and running. Environment variables are used for URL and credentials, falling back to localhost defaults.

import xmlrpc.client import os # NOTE: This assumes a 'supervisord' instance is running # and its XML-RPC interface is accessible, e.g., on port 9001. # You might need to configure supervisord.conf for this. # Example: [inet_http_server] # port=*:9001 # username=user # password=123 rpc_url = os.environ.get('SUPERVISOR_RPC_URL', 'http://localhost:9001/RPC2') rpc_username = os.environ.get('SUPERVISOR_RPC_USERNAME', '') rpc_password = os.environ.get('SUPERVISOR_RPC_PASSWORD', '') if rpc_username and rpc_password: # Add credentials to the URL if specified auth_url = rpc_url.replace('http://', f'http://{rpc_username}:{rpc_password}@') proxy = xmlrpc.client.ServerProxy(auth_url) else: proxy = xmlrpc.client.ServerProxy(rpc_url) try: # Get basic information about processes all_processes = proxy.supervisor.getAllProcessInfo() print(f"Found {len(all_processes)} supervised processes:") for p in all_processes: print(f" - Name: {p['name']}, State: {p['statename']}, PID: {p['pid']}") # Example: Check API version api_version = proxy.supervisor.getAPIVersion() print(f"Supervisor API Version: {api_version}") # Example: Stop a process (replace 'my_program' with an actual process name) # try: # print(f"Attempting to stop 'my_program': {proxy.supervisor.stopProcess('my_program')}") # except xmlrpc.client.Fault as e: # print(f"Error stopping process: {e}") except ConnectionRefusedError: print(f"ERROR: Connection refused. Is supervisord running and its RPC interface listening on {rpc_url}?", flush=True) except xmlrpc.client.Fault as e: print(f"ERROR: XML-RPC Fault: {e}", flush=True) except Exception as e: print(f"An unexpected error occurred: {e}", flush=True)
supervisorctl --version
Debug
Known issues
breakingSupervisor 4.0.0 introduced several breaking changes for programmatic interaction via XML-RPC. This includes changes to return types (e.g., booleans instead of integers) and the removal/renaming of some API methods like `getSupervisorState` (use `getState`) and `clearAllLogFiles`.
fix
Review the Supervisor 4.0.0 release notes and update client code to reflect the new XML-RPC API signatures and return types. Ensure Python 3.7+ is used as Python 2.6 support was dropped.
affects: 4.0.0 and newer
gotchaInstalling the `supervisor` package via `pip` only installs the `supervisord` server, `supervisorctl` client, and associated Python modules. It does not automatically configure, start, or manage `supervisord` as a system service. Users often mistakenly expect `pip install` to immediately launch a daemon.
fix
After installation, you must manually create a `supervisord.conf` file, then typically start `supervisord` via command line, or integrate it with a system's service manager (e.g., systemd, init.d) to run it as a persistent background daemon. Refer to the official Supervisor documentation for setup instructions.
affects: All versions
gotchaIncorrect permissions or paths in the `supervisord.conf` file can lead to `supervisord` failing to start, manage processes, or listen for connections. Common issues include `log_file` paths, `pid_file` locations, and permissions for the `unix_http_server` socket or `inet_http_server` ports.
fix
Always ensure paths specified in `supervisord.conf` exist and are writable by the user `supervisord` runs as. Verify that the user running `supervisord` has appropriate permissions for managing child processes. Check `supervisord` logs (`supervisord -c /path/to/supervisord.conf -n`) for startup errors.
affects: All versions
Errors
Common errors & fixes
supervisord: command not found
The `supervisord` executable is not in the system's PATH, or the supervisor package was not installed correctly (e.g., in a virtual environment not activated).
fix
Ensure the Python environment where supervisor was installed is active (e.g., `source venv/bin/activate`), or add the directory containing the `supervisord` executable to your system's PATH.
ERROR: Cannot open an HTTP connection to http://127.0.0.1:9001
The `supervisorctl` client cannot connect to the `supervisord` server, usually because `supervisord` is not running, its socket file is missing, or the client's configuration (`[supervisorctl]` section) does not match the server's configuration (`[supervisord]` section) for `inet_http_server` or `unix_http_server`.
fix
Verify that `supervisord` is running. Check your `supervisord.conf` file, specifically the `[supervisord]` and `[supervisorctl]` sections, to ensure `file` (for unix socket) or `port` and `username`/`password` (for HTTP) settings match and are correct. Restart `supervisord` if necessary.
FATAL Exited too quickly (process log may have details)
A program configured under `[program:yourprogram]` in `supervisord.conf` failed to start correctly or crashed immediately after starting, often due to an incorrect `command`, missing dependencies, permission issues, or environment problems within the program itself.
fix
Check the `stdout_logfile` and `stderr_logfile` specified in the program's configuration for detailed error messages. Manually run the `command` from your configuration file in the same user context and directory as supervisor to debug the underlying issue.
Error: [Errno 13] Permission denied
Supervisor is attempting to create a socket file, log file, or bind to a network port in a location or with permissions that the user running `supervisord` does not have write access to (e.g., a privileged port below 1024 or a protected directory).
fix
Change the `file` path for `unix_http_server`, `inet_http_server` port, or `log` paths in `supervisord.conf` to a directory where the `supervisord` user has write permissions (e.g., `/tmp`, `/var/tmp`, or a user-specific directory). If binding to a privileged port, either use a port above 1024 or configure system-level port forwarding.
Upgrade
Version history
4.3.0latest on PyPI · released Aug 23, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
62 hits · last 30 days
node
52
OpenAI (training)
1
Resources
supervisor — pip install supervisor · libregistry