This document describes the steps for installing mod_wsgi on a UNIX systemfrom the original source code.
Apache Requirements¶
The modpython page that you have to apply to use it with Python 2.3. Modpython needs to be recompiled naturally, but I have it working on a couple of Apache boxes (Linux and W2K) without any problems so far. Kai What patch? At what page? The latest release of modpython for Windows.
Apache 2.0, 2.2 or 2.4 can be used.
For Apache 2.0, 2.2 and 2.4, the single threaded ‘prefork’ or multithreaded‘worker’ Apache MPMs can be used. For Apache 2.4 the ‘event’ MPM can alsobe used.
The version of Apache and its runtime libraries must have be compiled withsupport for threading.
On Linux systems, if Apache has been installed from a package repository,you must have installed the corresponding Apache “dev” package as well.
For most Linux distributions, the “dev” package for Apache 2.X is“apache2-dev” where the corresponding Apache package was “apache2”. Somesystems however distinguish the “dev” package based on which MPM is used byApache. As such, it may also be called “apache2-worker-dev” or“apache2-prefork-dev”. If using Apache 2.X, do not mix things up and install“apache-dev” by mistake, which is the “dev” package for Apache 1.3 calledjust “apache”.
Python Requirements¶
Any Python 2.X version from Python 2.6 onwards can be used. For Python 3.X,you will need Python 3.3 or later.
The version of Python being used must have been compiled with support forthreading.
On Linux systems, if Python has been installed from a package repository,you must have installed the corresponding Python “dev” package as well.
Python should preferably be available as a shared library. If this is notthe case then base runtime memory usage of mod_wsgi will be greater.
Unpacking The Source Code¶
Source code tar balls can be obtained from:
After having downloaded the tar ball for the version you want to use,unpack it with the command:
Replace ‘X.Y’ with the actual version number for that being used.
Configuring The Source Code¶
To setup the package ready for building run the “configure” script fromwithin the source code directory:
The configure script will attempt to identify the Apache installation touse by searching in various standard locations for the Apache build toolsincluded with your distribution called “apxs2” or “apxs”. If not found inany of these standard locations, your PATH will be searched.
Which Python installation to use will be determined by looking for the“python” executable in your PATH.
If these programs are not in a standard location, they cannot be found inyour PATH, or you wish to use alternate versions to those found, the
--with-apxs
and --with-python
options can be used in conjunction withthe “configure” script:On some Linux distributions, such as SUSE and CentOS, it will be necessaryto use the
--with-apxs
option and specify either “/usr/sbin/apxs2-worker”or “/usr/sbin/apxs2-prefork”. This is necessary as the Linux distribtionsallow installation of “dev” packages for both Apache MPM variants at thesame time, whereas other Linux distributions do not.If you have multiple versions of Python installed and you are not usingthat which is the default, you may have to organise that the PATH inheritedby the Apache application when run will result in Apache finding thealternate version. Alternatively, the WSGIPythonHome directive shouldbe used to specify the exact location of the Python installationcorresponding to the version of Python compiled against. If this is notdone, the version of Python running within Apache may attempt to use thePython modules from the wrong version of Python.
Building The Source Code¶
Once the package has been configured, it can be built by running:
If the mod_wsgi source code does not build successfully, see:
If successful, the only product of the build process that needs to beinstalled is the Apache module itself. There are no separate Python codefiles as everything is done within C code compiled into the Apache module.
To install the Apache module into the standard location for Apache modulesas dictated by Apache for your installation, run:
Installation should be done as the ‘root’ user or ‘sudo’ command ifappropriate.
If you want to install the Apache module in a non standard locationdictated by how your operating system distribution structures theconfiguration files and modules for Apache, you will need to copy the filemanually into place.
If installing the Apache module by hand, the file is called ‘mod_wsgi.so’.The compiled Apache module can be found in the “.libs” subdirectory. Thename of the file should be kept the same when copied into its appropriatelocation.
Loading Module Into Apache¶
Once the Apache module has been installed into your Apache installation’smodule directory, it is still necessary to configure Apache to actuallyload the module.
Exactly how this is done and in which of the main Apache configurationfiles it should be placed, is dependent on which version of Apache you areusing and may also be influenced by how your operating system’s Apachedistribution has organised the Apache configuration files. You maytherefore need to check with any documentation for your operating system tosee in what way the procedure may need to be modified.
In the simplest case, all that is required is to add a line of the form:
into the main Apache “httpd.conf” configuration file at the same point thatother Apache modules are being loaded. The last option to the directiveshould either be an absolute path to where the mod_wsgi module file islocated, or a path expressed relative to the root of your Apacheinstallation. If you used “make” to install the package, see where itcopied the file to work out what to set this value to.
Restart Apache Web Server¶
Having adding the required directives you should perform a restart ofApache to check everything is okay. If you are using an unmodified Apachedistribution from the Apache Software Foundation, a restart is performedusing the ‘apachectl’ command:
If you see any sort of problem, or if you are upgrading from an olderversion of mod_wsgi, it is recommended you actually stop and the startApache instead:
Note that on many Linux distributions where Apache is prepackaged, theApache software has been modified and as a result the ‘apachectl’ commandmay not work properly or the command may not be present. On these systems,you will need to use whatever is the sanctioned method for restartingsystem services.
This may be via an ‘init.d’ script:
or via some special service maintenance script.
On Debian derived distributions, restarting Apache is usually done via the‘invoke-rc.d’ command:
On RedHat derived distributions, restarting Apache is usually done via the‘service’ command:
In nearly all cases the scripts used to restart Apache will need to be runas the ‘root’ user or via ‘sudo’.
In general, for any system where you are using a prepackaged version ofApache, it is wise to always check the documentation for that package orsystem to determine the correct way to restart the Apache service. This isbecause they often use a wrapper around ‘apachectl’, or replace it, with ascript which performs additional actions.
If all is okay, you should see a line of the form:
in the Apache error log file.
Cleaning Up After Build¶
To cleanup after installation, run:
If you need to build the module for a different version of Apache, youshould run:
and then rerun “configure” against the alternate version of Apache beforeattempting to run “make” again.
This document contains information about how to use Python virtualenvironments with mod_wsgi. You can use a Python virtual environmentcreated using virtualenv and virtualenvwrapper, or if using Python 3,the
pyvenv
or python-mvenv
commands.The purpose of a Python virtual environments is to allow one to createmultiple distinct Python environments for the same version of Python, butwith different sets of Python modules and packages installed. It isrecommended that you always use Python virtual environments and not installadditional Python packages direct into your Python installation.
A Python virtual environment is also required where it is necessary to runmultiple WSGI applications which have conflicting requirements as to whatversion of a Python module or package needs to be installed. They can alsobe used when distinct mod_wsgi daemon process groups are used to host WSGIapplications for different users and each user needs to be able toseparately install their own Python modules and packages.
How you configure mod_wsgi or setup your WSGI application script file for aPython virtual environment will depend on your specific requirements. Themore common scenarios are explained below.
Location of the Virtual Environment¶
Whichever method you use to create a Python virtual environment, before youuse it with mod_wsgi, you should validate what the location of the Pythonvirtual environment is. If using virtualenvwrapper this may be a nonobvious directory hidden away under your home directory.
The way to determine the location of the Python virtual environment is toactivate the Python virtual environment from an interactive shell so it isbeing used, and then run the command:
This will output the directory path you will use when setting up mod_wsgito use the Python virtual environment. For the purposes of the examplesbelow, it is assumed the location of any Python virtual environments areunder the
/usr/local/venvs
directory. A specific Python virtualenvironment may thus return for sys.prefix
:Note that this should be the root directory of the Python virtualenvironment, which in turn contains the
bin
and lib
directories forthe Python virtual environment. It is a common mistake when setting up aPython virtual environment with mod_wsgi to use the full path to thepython
executable instead of the root directory. That will not work, sodo not use the path for the python
executable as the location of thePython virtual environment, it has to be the root directory.Do be aware that the user that Apache runs your code as will need to beable to access the Python virtual environment. On some Linux distributions,the home directory of a user account is not accessible to other users.Rather than change the permissions on your home directory, it might bebetter to consider locating your WSGI application code and any Pythonvirtual environment outside of your home directory.
Virtual Environment and Python Version¶
When using a Python virtual environment with mod_wsgi, it is very importantthat it has been created using the same Python installation that mod_wsgiwas originally compiled for. It is not possible to use a Python virtualenvironment to force mod_wsgi to use a different Python version, or even adifferent Python installation.
You cannot for example force mod_wsgi to use a Python virtual environmentcreated using Python 3.5 when mod_wsgi was originally compiled for Python2.7. This is because the Python library for the Python installation it wasoriginally compiled against is linked directly into the mod_wsgi module.In other words, Python is embedded within mod_wsgi. When mod_wsgi is usedit does not run the command line
python
program to run the interpreterand thus why you can’t force it to use a different Python installation.The problem in trying to force mod_wsgi to use a different Pythoninstallation than what it was compiled for, even where it is the samePython version, is that the Python installation may itself not have beencompiled with the same options. This is especially a problem when it comesto issues around how Python stores Unicode characters in memory.
The end result is that if you want to use a different Python installationor version than what mod_wsgi was originally compiled for, you would needto re-install mod_wsgi such that it is compiled for the Python installationor version you do want to use. Do not try and use a Python virtualenvironment from one Python installation or version with mod_wsgi, whenmod_wsgi was compiled for a different one.
Daemon Mode (Single Application)¶
The preferred way of setting up mod_wsgi is to run each WSGI applicationin its own daemon process group. This is called daemon mode. A typicalconfiguration for running a WSGI application in daemon mode would be:
The
WSGIDaemonProcess
directive defines the daemon process group. TheWSGIProcessGroup
directive indicates that the WSGI application should berun within the defined daemon process group.As only the single application is being run within the daemon processgroup, the
WSGIApplicationGroup
directive is also being used. When thisis used with the %{GLOBAL}
value, it forces the WSGI application to runin the main Python interpreter context of each process. This is preferredin this scenario as some third party packages for Python which include Cextensions will not run in the Python sub interpreter contexts whichmod_wsgi would use by default. By using the main Python interpreter contextyou eliminate the possibility of such third party packages for Pythoncausing problems.To modify the configuration for this scenario to use a Python virtualenvironment, all you need to do is add the
python-home
option to theWSGIDaemonProcess
directive resulting in:All the additonal Python packages and modules would then be installed intothat Python virtual environment.
Daemon Mode (Multiple Applications)¶
If instead of running each WSGI application in a separate daemon processgroup as is the recommended practice, you are running multiple WSGIapplications in one daemon process group, a different approach to usingPython virtual environments is required.
For this scenario there are various ways the configuration could be setup. If mounting each WSGI application explicitly you might be using:
If instead the directory containing the WSGI application script files isbeing mounted, you might be using:
The use of the
WSGIDaemonProcess
and WSGIProcessGroup
is the same asbefore, however the WSGIApplicationGroup
directive is not being used.When the
WSGIApplicationGroup
directive isn’t being used to overridewhich Python interpreter context is being used, each WSGI application willbe run in its own Python sub interpreter context of the processes. This isnecessary as often WSGI application frameworks (Django being a primeexample), do not support running more than one instance of a WSGIapplication using the framework, in the same Python interpreter context atthe same time.In this scenario of running multiple WSGI applications in the same daemonprocess group, more than one change is possibly required. The changesrequired depend on whether or not all WSGI applications should share thesame Python virtual environment.
If all of the WSGI applications should share the same Python virtualenvironment, then the same change as was performed above for the singleapplication case would be made. That is, add the
python-home
optionto the WSGIDaemonProcess
directive:All the additonal Python packages and modules that any of the WSGIapplications required would then be installed into that Python virtualenvironment. Because it is a shared environment, they must all use the sameversion of any specific Python package or module.
If instead of all WSGI applications using the same Python virtualenvironment each needed their own, then a change will instead need to bemade in each of the WSGI script files for the applications.
How this is done will depend on how the Python virtual environment iscreated.
If the Python virtual environment is created using virtualenv orvirtualenvwrapper, the WSGI script for each application should bemodified to include code of the following form:
Because each WSGI application is to use a separate Python virtualenvironment, the value of the
python_home
variable would be setdifferently for each WSGI script file, with it referring to the rootdirectory of the respective Python virtual environments.This code should be placed in the WSGI script file before any other moduleimports in the WSGI script file, with the exception of
from__future__
imports used to enable Python feature flags.Important to note is that when the Python virtual environment is activatedfrom within the WSGI script, what happens is a bit different to when the
python-home
option to WSGIDaemonProcess
is used.When activating the Python virtual environment from within the WSGI scriptfile, only the
site-packages
directory from the Python virtualenvironment is being used. This directory will be added to the Pythonmodule search path, along with any additional directories related to thesite-packages
directory registered using .pth
files present in thesite-packages
directory. This will be placed at the start of theexisting sys.path
.The consequence of this is that the Python virtual environment isn’tcompletely overriding the original Python installation the Python virtualenvironment was created from. This means that if the main Pythoninstallation had additional Python packages installed they will alsopotentially be visible to the WSGI application.
That this occurs could cause confusion as you might for example think youhad all the packages you require listed in your
requirements.txt
filefor pip
, but didn’t and so a package may not have been installed. Ifthat package was installed in the main Python installation, it would bepicked up from there, but it might be the wrong version and havedependencies on versions of other packages for which you have differentversions installed in your Python virtual environment and which are foundinstead of those in the main Python installation.To avoid such problems, when activating the Python virtual environmentfrom within the WSGI script file, it is necessary to still set the
python-home
option of the WSGIDaemonProcess
directive, but set it toan empty Python virtual environment which has had no additional packagesinstalled:By doing this, the main Python installation will not be consulted andinstead it will fallback to the empty Python virtual environment. ThisPython virtual environment should remain empty and you should not installadditional Python packages or modules into it, or you will cause the samesort of conflicts that can arise with the main Python installation when itwas being used.
When needing to activate the Python virtual environment from within theWSGI script file as described, it is preferred that you be using the eithervirtualenv or virtualenvwrapper to create the Python virtualenvironment. This is because they both provide the
activate_this.py
script file which does all the work of setting up sys.path
. When youuse either pyvenv
or python-mvenv
with Python 3, no suchactivation script is provided.So use virtualenv or virtualenvwrapper if you can. If you cannot forsome reason and are stuck with
pyvenv
or python-mvenv
, you caninstead use the following code in the WSGI script file:As before this code should be placed in the WSGI script file before anyother module imports in the WSGI script file, with the exception of
from__future__
imports used to enable Python feature flags.When using this method, do be aware that the additions to the Python modulesearch path are made at the end of
sys.path
. For that reason, you mustset the python-home
option to WSGIDaemonProcess
to the location ofan empty Python virtual environment. If you do not do this, any additionalPython package installed in the main Python installation will hide those inthe Python virtual environment for the application.There is extra code you could add which would reorder
sys.path
to makeit work in an equivalent way to the activate_this.py
script providedwhen you use virtualenv or virtualenvwrapper but it is messy and moretrouble than it is worth:It is better to avoid needing to manually activate the Python virtualenvironment from inside of a WSGI script by using a separate daemon processgroup per WSGI application. At the minimum, at least avoid
pyvenv
andpython-mvenv
.Embedded Mode (Single Application)¶
The situation for running a single WSGI application in embedded mode is notmuch different to running a single WSGI application in daemon mode. In thecase of embedded mode, there is though no
WSGIDaemonProcess
directive.The typical configuration when running a single WSGI application inembedded module might be:
The
WSGIDaemonProcess
and WSGIProcessGroup
directives are gone, butthe WSGIApplicationGroup
directive is still used to force the WSGIapplication to run in the main Python interpreter context of each of theApache worker processes. This is to avoid those issues with some thirdparty packages for Python with C extensions as mentioned before.In this scenario, to set the location of the Python virtual environmentto be used, the
WSGIPythonHome
directive is used:Note that if the WSGI application is being setup within the context of anApache
VirtualHost
, the WSGIPythonHome
cannot be placed inside ofthe VirtualHost
. Instead it must be placed outside of allVirtualHost
definitions. This is because it applies to the whole Apacheinstance and not just the single VirtualHost
.Embedded Mode (Multiple Applications)¶
Running multiple applications in embedded mode is also similar to whenrunning multiple WSGI applications in one daemon process group. You stillneed to ensure each WSGI application runs in its own Python sub interpretercontext to avoid potential issues with Python web frameworks that don’tallow more than one WSGI application to be using it at the same time in aPython interpreter context.
If mounting each WSGI application explicitly you might be using:
If instead the directory containing the WSGI application script files isbeing mounted, you might be using:
In this scenario, to set the location of the Python virtual environmentto be used by all WSGI application, the
WSGIPythonHome
directive is used:If the WSGI application is being setup within the context of an Apache
VirtualHost
, the WSGIPythonHome
cannot be placed inside of theVirtualHost
. Instead it must be placed outside of all VirtualHost
definitions. This is because it applies to the whole Apache instance andnot just the single VirtualHost
.If each WSGI application needs its own Python virtual environment, thenactivation of the Python virtual environment needs to be performed in theWSGI script itself as explained previously for the case of daemon modebeing used. The
WSGIPythonHome
directive should be used to refer to anempty Python virtual environment if needed to ensure that any additionalPython packages in the main Python installation don’t interfere with whatpackages are installed in the Python virtual environment for each WSGIapplication.Adding Additional Module Directories¶
The
python-home
option to WSGIDaemonProcess
and theWSGIPythonHome
directive are the preferred way of specifying thelocation of the Python virtual environment to be used. If necessary,activation of the Python virtual environment can also be performed from theWSGI script file itself.If you need to add additional directories to search for Python packages ormodules this can also be done. You may want to do this where you need tospecify where the actual WSGI application is located, where a WSGI scriptfile needs to import application specific modules.
If you are using daemon mode and want to add additional directories to thePython module search path, you can use the
python-path
option toWSGIDaemonProcess
:This option would be in addition to the
python-home
option used tospecify where the Python virtual environment is located.If you are using embedded mode, you can use the
WSGIPythonPath
directive:This directive is in addition to the
WSGIPythonHome
directive used tospecify where the Python virtual environment is located.In either case, if you need to specify more than one directory, they can beseparated using a ‘:’ character.
If you are having to activate the Python virtual enviromment from within aWSGI script and need to add additional directories to the Python modulesearch path, you should modify
sys.path
directly from the WSGI scriptfile.Note that prior practice was that these ways of setting the Python modulesearch path were used to specify the location of the Python virtualenvironment. Specifically, they were used to add the
site-packages
directory of the Python virtual environment. You should not do that.The better way to specify the location of the Python virtual environment isusing the
python-home
option of the WSGIDaemonProcess
directive fordaemon mode, or the WSGIPythonHome
directive for embedded mode. Theseways of specifying the Python virtual environment have been available sincemod_wsgi 3.0 and Linux distributions have not shipped such an old versionof mod_wsgi for quite some time. If you are using the older way, pleaseupdate your configurations.