When deploying Trac through uWSGI with a Python virtual environment, many developers encounter import errors despite correct path configurations. The error typically manifests as:

ImportError: No module named trac.web.main
unable to load app 0 (mountpoint='') (callable not found or import error)

Here's a verified working configuration that properly activates the virtual environment:

[uwsgi]
chdir = /srv/http/trac/projects/my_project
home = /srv/http/trac/venv
pythonpath = /srv/http/trac/venv/lib/python2.7/site-packages
module = trac.web.main:dispatch_request

socket = 127.0.0.1:3032
uid = www-data
gid = www-data
env = TRAC_ENV=/srv/http/trac/projects/my_project
master = true
processes = 1
vacuum = true

Critical parameters often missed:

• chdir: Sets working directory before loading app
• pythonpath: Explicitly points to site-packages
• vacuum: Cleanup socket files on exit

Method 1: Using virtualenv parameter

virtualenv = /srv/http/trac/venv

Method 2: Systemd service file example

[Unit]
Description=uWSGI instance for Trac
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/srv/http/trac/projects/my_project
Environment="TRAC_ENV=/srv/http/trac/projects/my_project"
ExecStart=/usr/local/bin/uwsgi --ini /etc/uwsgi/vassals-available/my_project.ini

Verify environment activation with:

uwsgi --ini config.ini --need-app --py-autoreload 1

Check Python path resolution:

uwsgi --python-version
uwsgi --python-path

For production environments, consider these optimizations:

harakiri = 30
max-requests = 5000
buffer-size = 65535

The error occurs when uWSGI fails to locate Python packages installed in a virtualenv, specifically throwing ImportError: No module named trac.web.main. This typically happens when:

• uWSGI isn't properly configured to use the virtualenv's Python interpreter
• The PYTHONPATH isn't correctly set
• Virtualenv activation isn't properly handled in the uWSGI configuration

Here's the corrected configuration that ensures proper virtualenv usage:

[uwsgi]
master = true
processes = 4
socket = 127.0.0.1:3032
chmod-socket = 660

# Virtualenv configuration (CRITICAL)
virtualenv = /srv/http/trac/venv
pythonpath = /srv/http/trac/venv/lib/python2.7/site-packages

# Permissions
gid = www-data
uid = www-data

# Trac specific
env = TRAC_ENV=/srv/http/trac/projects/my_project
module = trac.web.main:dispatch_request

The working solution makes these critical changes:

# Old (problematic)
home = /srv/http/trac/venv/
no-site = true

# New (working)
virtualenv = /srv/http/trac/venv
pythonpath = /srv/http/trac/venv/lib/python2.7/site-packages

To confirm uWSGI is using the virtualenv correctly:

# Check Python interpreter path
uwsgi --ini your_config.ini --show-config | grep python-script

# Verify sys.path
uwsgi --ini your_config.ini --python-version

For command-line execution instead of INI files:

uwsgi --http :8000 \
--virtualenv /srv/http/trac/venv \
--pythonpath /srv/http/trac/venv/lib/python2.7/site-packages \
--module trac.web.main:dispatch_request \
--env TRAC_ENV=/srv/http/trac/projects/my_project \
--uid www-data --gid www-data

• Mixing system Python and virtualenv Python installations
• Incorrect permissions on virtualenv directories
• Missing pythonpath directive when using non-standard locations
• Forgetting to install uWSGI inside the virtualenv (pip install uwsgi)

Add these to your configuration for detailed logging:

[uwsgi]
...
logto = /var/log/uwsgi/trac.log
disable-logging = false
verbose = true