Requirements

This page lists the platform, Apache, Python, and build-time requirements for building and running mod_wsgi. For walk-through install steps see Getting Started; for the broader install landing page see Installation.

Operating system

mod_wsgi runs on UNIX-like systems and, on a provisional basis, on Windows.

  • Linux is the primary, well-tested platform.

  • macOS is supported using an Apache HTTP Server installed via Homebrew. Apple removed the build tooling required to compile third-party Apache modules against the system Apache, so the Apple-shipped Apache cannot be used; see Installation On macOS.

  • Windows support under the 6.x release line is provisional. The project’s author does not run Windows and continued Windows support depends on community testing and bug reports. Daemon mode is not available on Windows; only embedded mode is supported. mod_wsgi-express start-server is also known not to work on Windows, so pip install mod_wsgi is the canonical install path on that platform. See Project Status for details.

Apache HTTP Server

Apache HTTP Server 2.4 is required. mod_wsgi does not support older Apache versions.

On UNIX-like systems any of the standard Apache MPMs can be used:

  • prefork — single-threaded, multi-process.

  • worker — multi-threaded, multi-process.

  • event — multi-threaded, multi-process, asynchronous connection handling.

On Windows the mpm_winnt MPM is used.

The Apache build must have been compiled with thread support, even when only the single-threaded prefork MPM is in use, because the daemon processes mod_wsgi creates in daemon mode are themselves multithreaded by default.

Python

Python 3.10 or later is required.

The Python installation must have been built such that an embeddable shared library is available — for example libpython3.X.so on Linux, Python.framework on macOS. mod_wsgi embeds the Python interpreter into Apache processes, which is not possible against a static-only Python build.

Most distribution-provided Python packages, Homebrew Python, and official python.org installers satisfy this requirement out of the box. Some hand-built Python installations and stripped-down container-image Pythons do not; building mod_wsgi against such an installation will fail at the link step.

You can check whether your Python install has a shared library available with:

python3 -c 'import sysconfig; print(sysconfig.get_config_var("Py_ENABLE_SHARED"))'

A return value of 1 indicates a shared build.

The Anaconda Python distribution can cause shared-library conflicts when mod_wsgi is loaded into an Apache instance alongside other modules that link against system libraries Anaconda also bundles — mod_ssl against the Anaconda-bundled SSL libraries, mod_php against image-manipulation libraries, and similar.

If you encounter problems building or running mod_wsgi against your Python installation, see Installation Issues for the known causes and workarounds.

Build toolchain

mod_wsgi compiles native C code that links against both Apache and Python. Building it — whether by running ./configure && make on a source tarball, or by running pip install mod_wsgi — requires a working compile toolchain on the host:

  • Python development headers (python3-dev on Debian/Ubuntu, python3-devel on RHEL/Fedora; included with Homebrew Python on macOS).

  • Apache development headers and the apxs build tool (apache2-dev on Debian/Ubuntu, httpd-devel on RHEL/Fedora, brew install httpd on macOS).

  • A C compiler such as gcc or clang (on macOS, install the Xcode Command Line Tools with xcode-select --install).

If you are installing mod_wsgi from a Linux distribution package (libapache2-mod-wsgi-py3 on Debian/Ubuntu, python3-mod_wsgi on RHEL/Fedora, or similar) you do not need a build toolchain on the host; the package ships a pre-compiled module.

WSGI specification compliance

mod_wsgi can host any Python web application that complies with the WSGI specification (PEP 3333). The implementation is strict in its interpretation of the specification. Other WSGI servers may be more lenient and accept non-conforming applications. If a Python web application that runs successfully under another WSGI server fails or behaves oddly under mod_wsgi, the most common cause is the application not conforming strictly to WSGI.