Fixing “Invalid command ‘PythonHandler'” Error in Django/Apache2 mod_python Deployment on Debian


2 views

Many developers transitioning from older Apache setups encounter this specific error when trying to configure Django with mod_python. The core issue stems from missing module dependencies and configuration nuances in modern Debian systems.

The immediate solution requires enabling the mod_python module in Apache2:

sudo a2enmod python
sudo service apache2 restart

However, this is just the first step. Modern Debian systems often require additional configuration due to changes in Apache's module handling.

Here's a working configuration for /etc/apache2/sites-available/000-default.conf:

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html

    <Location "/">
        SetHandler python-program
        PythonHandler django.core.handlers.modpython
        SetEnv DJANGO_SETTINGS_MODULE hellodjango1.settings
        PythonOption django.root /
        PythonDebug On
        PythonPath "['/path/to/your/project'] + sys.path"
    </Location>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

While we're fixing the mod_python issue, it's worth noting the Django community now recommends:

  • mod_wsgi for production deployments
  • Gunicorn or uWSGI behind Nginx for better performance

If you still encounter issues, verify these key points:

# Check if mod_python is properly loaded
apache2ctl -M | grep python

# Verify Python path accessibility
sudo -u www-data python -c "import sys; print(sys.path)"

Remember to check Apache error logs for detailed diagnostics:

tail -f /var/log/apache2/error.log

Django applications often fail due to filesystem permissions. Ensure your www-data user has proper access:

sudo chown -R www-data:www-data /path/to/your/project
sudo find /path/to/your/project -type d -exec chmod 755 {} \;
sudo find /path/to/your/project -type f -exec chmod 644 {} \;

When migrating from Apache 1.3 to Apache 2.x, many developers encounter this specific error because the mod_python module isn't properly enabled. The error occurs when Apache tries to process directives that require mod_python without the module being loaded.

First, check if mod_python is actually installed:


sudo apt-get install libapache2-mod-python

Then verify the module is enabled in Apache:


apache2ctl -M | grep python

Here's a full example of a working virtual host configuration that solved this issue on Debian 11:


<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/yourproject
    
    <Directory /var/www/yourproject>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
    
    <Location "/">
        SetHandler python-program
        PythonHandler django.core.handlers.modpython
        SetEnv DJANGO_SETTINGS_MODULE yourproject.settings
        PythonDebug On
        PythonPath "['/var/www'] + sys.path"
    </Location>
    
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

If you still encounter issues:

  1. Verify module loading in /etc/apache2/mods-enabled/python.load
  2. Check Apache error logs: tail -f /var/log/apache2/error.log
  3. Test Python integration separately with a simple test handler

While this solution works, consider that the Django community now recommends:

  • mod_wsgi for production deployments
  • Gunicorn/uWSGI behind Nginx
  • Docker containers for easier deployment