⚠️ PROJECT STATUS: MAINTENANCE MODE
uWSGI is in maintenance mode (announced 2024). The project receives only bugfixes and updates for new language APIs. For new projects, consider Gunicorn, Uvicorn, or Granian.
| Installation Method | Configuration Path |
|---|---|
| pip install | Custom location (e.g., /etc/uwsgi/, /app/) |
| Debian/Ubuntu | /etc/uwsgi/apps-available/ |
| RHEL/EPEL | /etc/uwsgi/ |
| Docker | Custom (mounted volume) |
uWSGI supports multiple configuration formats:
| Format | Extension | Example |
|---|---|---|
| INI | .ini |
Most common |
| YAML | .yaml, .yml |
Alternative |
| JSON | .json |
Alternative |
| Command-line | N/A | Direct options |
# /etc/uwsgi/myapp.ini
[uwsgi]
module = myapp:app
master = true
processes = 4
socket = 127.0.0.1:8000
chmod-socket = 660
vacuum = true
die-on-term = true
| Option | Description |
|---|---|
module |
Python application module |
master |
Enable master process |
processes |
Number of worker processes |
socket |
Bind to socket (TCP or Unix) |
chmod-socket |
Socket permissions |
vacuum |
Clean up on exit |
die-on-term |
Exit on SIGTERM |
# /etc/uwsgi/myapp.ini
[uwsgi]
# Application
module = myapp:app
chdir = /var/www/myapp
home = /var/www/myapp/venv
# Process management
master = true
processes = 4
threads = 2
cheaper = 2
cheaper-initial = 2
cheaper-step = 1
# Socket binding
socket = 127.0.0.1:8000
chmod-socket = 660
listen = 100
# Timeouts
socket-timeout = 65
http-timeout = 65
# Logging
logto = /var/log/uwsgi/myapp.log
log-maxsize = 52428800
log-backupname = /var/log/uwsgi/myapp.log.old
# Process info
pidfile = /var/run/uwsgi/myapp.pid
stats = 127.0.0.1:9191
# Cleanup
vacuum = true
die-on-term = true
single-interpreter = true
# Security
uid = www-data
gid = www-data
# Memory management
max-requests = 5000
max-requests-delta = 500
reload-on-rss = 512
reload-on-as = 1024
# Request handling
buffer-size = 65535
post-buffering = 4096
# Protocol
protocol = uwsgi
thunder-lock = true
harakiri = 30
harakiri-verbose = true
# uwsgi.yaml
uwsgi:
module: myapp:app
master: true
processes: 4
socket: 127.0.0.1:8000
chmod-socket: 660
vacuum: true
die-on-term: true
logto: /var/log/uwsgi/myapp.log
socket = 127.0.0.1:8000
socket = /var/run/uwsgi/myapp.sock
chmod-socket = 660
chown-socket = www-data:www-data
http = :8000
processes = 4
cheaper = 2
cheaper-initial = 2
cheaper-step = 1
processes = 8
# Reload on memory threshold
reload-on-rss = 512
reload-on-as = 1024
# Reload after N requests
max-requests = 5000
# Log file
logto = /var/log/uwsgi/myapp.log
# Log rotation
log-maxsize = 52428800
log-backupname = /var/log/uwsgi/myapp.log.old
# Log format
log-date = true
log-4xx = true
log-5xx = true
# Syslog
# log-syslog = true
# log-syslog-name = uwsgi-myapp
Emperor mode manages multiple uWSGI applications (vassals):
# /etc/uwsgi/emperor.ini
[uwsgi]
emperor = /etc/uwsgi/vassals
uid = www-data
gid = www-data
logto = /var/log/uwsgi/emperor.log
# /etc/uwsgi/vassals/app1.ini
[uwsgi]
module = app1:app
socket = /var/run/uwsgi/app1.sock
chdir = /var/www/app1
uid = www-data
gid = www-data
server {
listen 80;
server_name example.com;
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:8000;
# Or for Unix socket:
# uwsgi_pass unix:/var/run/uwsgi/myapp.sock;
uwsgi_param Host $host;
uwsgi_param X-Real-IP $remote_addr;
uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
uwsgi_param X-Forwarded-Proto $scheme;
}
location /static {
alias /var/www/myapp/static;
expires 30d;
}
}
<VirtualHost *:80>
ServerName example.com
<Location />
Require all granted
</Location>
ProxyPass / uwsgi://127.0.0.1:8000/
ProxyPassReverse / http://127.0.0.1:8000/
</VirtualHost>
env = DJANGO_SETTINGS_MODULE=myapp.settings
env = FLASK_ENV=production
env = PYTHONPATH=/var/www/myapp
home = /var/www/myapp/venv
# or
virtualenv = /var/www/myapp/venv
# Enable stats server
stats = 127.0.0.1:9191
stats-http = true
# Using uwsgi command
uwsgi --connect-and-read tcp:127.0.0.1:9191
# Using curl (if stats-http enabled)
curl http://127.0.0.1:9191
# Using systemctl
sudo systemctl reload uwsgi
# Using PID file
uwsgi --reload /var/run/uwsgi/myapp.pid
# Using touch reload
touch /var/run/uwsgi/myapp.reload
# Using systemctl
sudo systemctl stop uwsgi
# Using PID file
uwsgi --stop /var/run/uwsgi/myapp.pid
# Test configuration
uwsgi --ini /etc/uwsgi/myapp.ini
# Check syntax
uwsgi --ini /etc/uwsgi/myapp.ini --check-config
[uwsgi]
chdir = /var/www/django_project
module = django_project.wsgi:application
home = /var/www/django_project/venv
[uwsgi]
chdir = /var/www/flask_app
module = app:app
home = /var/www/flask_app/venv
⚠️ Note: For FastAPI and other ASGI applications, use Uvicorn or Granian instead of uWSGI.
# Not recommended - use Uvicorn instead
[uwsgi]
module = app:app
http = :8000
⚠️ Maintenance Mode Warning
Security patches may be slower due to maintenance mode status.
uid, gid)chmod-socket)harakiri, max-requests)See uWSGI Security and uWSGI Hardening for security guidance.
Squeezing every bit of performance from your uWSGI installation? Our experts help with:
Optimize your setup: office@linux-server-admin.com | Contact Us