Learn how we configure Supervisor to manage Python applications on Linux. This step-by-step guide covers installation, configuration, automatic restarts, logging, virtual environments, and production best practices for reliable Python services.
Prerequisites
Before we begin, let’s ensure we have the following in place:
- A Ubuntu 24.04 dedicated server or KVM VPS.
- A basic programming knowledge.
- Python application.
Learn how we configure Supervisor to manage Python applications on Linux.
Introduction
Running a Python application in production requires more than simply executing a script. When applications crash, restart after a server reboot, or need multiple worker processes, a process manager becomes essential.
Supervisor is a lightweight and reliable process control system for Unix-based environments. It allows us to monitor Python applications, automatically restart failed processes, manage logs, and run services in the background.
This guide explains how to configure Supervisor for Python applications, starting with installation and moving into advanced configuration used in production environments.
Install Supervisor
Most modern Linux distributions include Supervisor in their official repositories.
Update the system package list first.
sudo apt update
Install Supervisor.
sudo apt install supervisor -y
After installation, start the service and enable it during system startup.
sudo systemctl start supervisor
sudo systemctl enable supervisor
Verify that Supervisor is running.
sudo systemctl status supervisor
The output should show the service in an active (running) state.
Supervisor is now ready to manage application processes.
Understand the Supervisor Configuration Structure
Supervisor stores its configuration files in the following directory.
/etc/supervisor/conf.d/
Each application typically receives its own configuration file. This structure keeps process management organized and easy to maintain.
Supervisor reads these files automatically when the service starts or reloads.
Prepare a Python Application
Before configuring Supervisor, the Python application should run correctly from the command line.
Example application:
# app.py
import time
while True:
print("Application running...")
time.sleep(10)
Test the script.
python3 app.py
If the application runs successfully, it is ready to be managed by Supervisor.
Create a Supervisor Configuration File
Create a configuration file for the application.
sudo nano /etc/supervisor/conf.d/python_app.conf
Add the following configuration.
[program:python_app]
command=/usr/bin/python3 /var/www/python_app/app.py
directory=/var/www/python_app
autostart=true
autorestart=true
startretries=3
stderr_logfile=/var/log/python_app.err.log
stdout_logfile=/var/log/python_app.out.log
user=www-data
Explanation of important parameters:
command
Defines the exact command Supervisor runs to start the application.
directory
Working directory where the application executes.
autostart
Automatically starts the process when Supervisor launches.
autorestart
Restarts the application if it stops unexpectedly.
startretries
Number of restart attempts before marking the program as failed.
stdout_logfile / stderr_logfile
Stores application logs for troubleshooting.
user
Defines the Linux user that runs the process.
Reload Supervisor Configuration
After creating the configuration file, reload Supervisor so it recognizes the new program.
sudo supervisorctl reread
Then apply the configuration.
sudo supervisorctl update
Start the application.
sudo supervisorctl start python_app
Check the status.
sudo supervisorctl status
Supervisor should report the application as RUNNING.
Manage Python Processes with Supervisor
Supervisor provides several commands to control application processes.
Stop the application.
sudo supervisorctl stop python_app
Start the application again.
sudo supervisorctl start python_app
Restart the process.
sudo supervisorctl restart python_app
View process status.
sudo supervisorctl status
These commands allow administrators to control services without directly interacting with the application itself.
Enable Automatic Restart on Failure
Production environments require applications to recover automatically after unexpected failures.
Supervisor provides built-in restart logic.
Example configuration.
autorestart=unexpected
exitcodes=0
startsecs=5
Meaning:
autorestart=unexpected
Restarts the process only when it exits unexpectedly.
exitcodes=0
Exit code treated as normal termination.
startsecs
Minimum number of seconds the process must stay alive before considered successfully started.
This setup prevents restart loops caused by configuration errors.
Configure Environment Variables
Many Python applications depend on environment variables.
Supervisor allows environment configuration directly inside the program block.
Example:
environment=APP_ENV="production",DATABASE_URL="postgresql://user:pass@localhost/db"
This ensures the application starts with the required runtime configuration.
Run Applications with Virtual Environments
Most production Python projects use virtual environments.
Supervisor should execute the Python binary inside the virtual environment.
Example configuration:
command=/var/www/myproject/venv/bin/python /var/www/myproject/app.py
This ensures the application uses the correct dependency versions.
Run Multiple Worker Processes
Some applications require multiple worker processes for better performance.
Supervisor supports this using the numprocs option.
Example configuration:
[program:worker]
command=/var/www/app/venv/bin/python worker.py
process_name=%(program_name)s_%(process_num)02d
numprocs=4
autostart=true
autorestart=true
Supervisor will launch four worker processes automatically.
Centralized Log Management
Production applications generate logs that should be easy to inspect.
Supervisor allows separate logs for stdout and stderr.
Example:
stdout_logfile=/var/log/app_worker.log
stderr_logfile=/var/log/app_worker_error.log
Logs can be monitored in real time.
tail -f /var/log/app_worker.log
This helps quickly identify runtime errors or application behavior.
Protect the Supervisor Interface
Supervisor includes a control interface that can be secured using authentication.
Example configuration in /etc/supervisor/supervisord.conf.
[inet_http_server]
port=127.0.0.1:9001
username=admin
password=strongpassword
This allows secure access to the Supervisor management interface while restricting remote exposure.
Reload Configuration Without Restarting Services
Supervisor allows configuration changes without restarting the entire service.
sudo supervisorctl reread
sudo supervisorctl update
This reloads modified program configurations while keeping other services running.
Best Practices for Production Environments
Several practices improve reliability when running Python applications with Supervisor.
Use dedicated Linux users for applications instead of root.
Store application logs in /var/log to simplify monitoring.
Always test application commands manually before adding them to Supervisor.
Use virtual environments to isolate dependencies.
Enable automatic restarts for production workloads.
Maintain separate configuration files for each application.
These practices help maintain stable and predictable services.
Summary
Supervisor is a powerful process manager that simplifies running Python applications in production environments. It provides automatic restarts, centralized logging, process monitoring, and flexible configuration.
By integrating Supervisor into application deployments, teams can ensure Python services remain available even after crashes or system reboots.
With proper configuration, Supervisor becomes a reliable foundation for managing background services, worker processes, and long-running Python applications across Linux servers.
