{"id":1736,"library":"supervisor","title":"Supervisor","description":"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.","status":"active","version":"4.3.0","language":"en","source_language":"en","source_url":"https://github.com/Supervisor/supervisor","tags":["process manager","system service","daemon","process control","monitoring","xml-rpc"],"install":[{"cmd":"pip install supervisor","lang":"bash","label":"Install Supervisor"}],"dependencies":[],"imports":[{"note":"For utilities to interact with Supervisor from a supervised child process, e.g., for event listening.","symbol":"childutils","correct":"from supervisor import childutils"},{"note":"Standard Python XML-RPC client for external control of the running 'supervisord' instance. The 'supervisor' package itself doesn't export a direct client class.","symbol":"ServerProxy","correct":"from xmlrpc.client import ServerProxy"}],"quickstart":{"code":"import xmlrpc.client\nimport os\n\n# NOTE: This assumes a 'supervisord' instance is running\n# and its XML-RPC interface is accessible, e.g., on port 9001.\n# You might need to configure supervisord.conf for this.\n# Example: [inet_http_server]\n#          port=*:9001\n#          username=user\n#          password=123\n\nrpc_url = os.environ.get('SUPERVISOR_RPC_URL', 'http://localhost:9001/RPC2')\nrpc_username = os.environ.get('SUPERVISOR_RPC_USERNAME', '')\nrpc_password = os.environ.get('SUPERVISOR_RPC_PASSWORD', '')\n\nif rpc_username and rpc_password:\n    # Add credentials to the URL if specified\n    auth_url = rpc_url.replace('http://', f'http://{rpc_username}:{rpc_password}@')\n    proxy = xmlrpc.client.ServerProxy(auth_url)\nelse:\n    proxy = xmlrpc.client.ServerProxy(rpc_url)\n\ntry:\n    # Get basic information about processes\n    all_processes = proxy.supervisor.getAllProcessInfo()\n    print(f\"Found {len(all_processes)} supervised processes:\")\n    for p in all_processes:\n        print(f\"  - Name: {p['name']}, State: {p['statename']}, PID: {p['pid']}\")\n\n    # Example: Check API version\n    api_version = proxy.supervisor.getAPIVersion()\n    print(f\"Supervisor API Version: {api_version}\")\n\n    # Example: Stop a process (replace 'my_program' with an actual process name)\n    # try:\n    #     print(f\"Attempting to stop 'my_program': {proxy.supervisor.stopProcess('my_program')}\")\n    # except xmlrpc.client.Fault as e:\n    #     print(f\"Error stopping process: {e}\")\n\nexcept ConnectionRefusedError:\n    print(f\"ERROR: Connection refused. Is supervisord running and its RPC interface listening on {rpc_url}?\", flush=True)\nexcept xmlrpc.client.Fault as e:\n    print(f\"ERROR: XML-RPC Fault: {e}\", flush=True)\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\", flush=True)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Supervisor 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`.","severity":"breaking","affected_versions":"4.0.0 and newer"},{"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.","message":"Installing 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Incorrect 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}