mod_wsgi

5.0.2 verified Fri May 01 auth: no python

mod_wsgi is an Apache HTTP Server module that provides a WSGI compliant interface for hosting Python web applications under Apache. It supports both embedded and daemon modes, with the ability to run multiple Python versions and virtual environments. Current version 5.0.2 (2024-02-19) requires Python >=3.8. Release cadence is irregular, typically minor updates every few years.

pip install mod-wsgi

Common errors

error ImportError: No module named 'mod_wsgi' ↓

cause mod_wsgi is an Apache module, not a Python package that can be imported directly in Python code.

fix

Do not import 'mod_wsgi' in Python scripts. Use 'pip install mod-wsgi' to build the module, then load it in Apache with 'LoadModule wsgi_module modules/mod_wsgi.so'.

error Unable to load wsgi module: mod_wsgi.so: cannot open shared object file ↓

cause mod_wsgi.so is not in Apache's module directory or Apache can't find it.

fix

Run 'sudo apt install libapache2-mod-wsgi-py3' on Debian/Ubuntu or build with 'pip install mod-wsgi' and copy the .so to Apache modules directory.

error Fatal Python error: init_sys_streams: can't initialize sys standard streams ↓

cause Occurs when mod_wsgi runs embedded in Apache's child processes that lack proper stdio.

fix

Use daemon mode with 'WSGIDaemonProcess' directive instead of embedded mode.

Warnings

breaking Thread limit issues when using embedded mode with threaded MPM (worker/event). Default threads per process may cause crashes if exceeded. ↓

fix Use 'WSGIDaemonProcess' to isolate application in daemon mode with controlled thread count.

gotcha Memory leak when using Python threads or blocking I/O inside mod_wsgi daemon mode with multiple processes. ↓

fix Set 'WSGIApplicationGroup %{GLOBAL}' if using single-threaded frameworks; use 'maximum-requests' to recycle processes.

deprecated Python 2 support removed in 5.0.0; mod_wsgi 4.x still available for Python 2. ↓

fix Migrate to Python 3 and upgrade mod_wsgi to >=5.0.0.

deprecated The 'mod_wsgi-express' command is the recommended development server but is not production-ready. ↓

fix Use Apache with mod_wsgi in production; mod_wsgi-express is for testing only.

gotcha Virtual environments: must be activated before Apache start or specify Python home via WSGIPythonHome. ↓

fix Set 'WSGIPythonHome /path/to/venv' in Apache config.

Imports

application
```
def application(environ, start_response): ...  # then assign to module-level 'application'
```
WSGI application callable must be named 'application' (default) or specified via WSGIApplicationGroup directive.

Quickstart

Minimal WSGI application file. Place in your Apache document root or a directory accessible to Apache, then configure Apache with 'WSGIScriptAlias / /path/to/myapp.wsgi'.

# Save as myapp.wsgi
def application(environ, start_response):
    status = '200 OK'
    output = b'Hello, World!'
    response_headers = [('Content-type', 'text/plain'), ('Content-Length', str(len(output)))]
    start_response(status, response_headers)
    return [output]