Fix cPanel Passenger "Web Application Could Not Be Started" for Django

Problem statement

On a cPanel host using Setup Python App, the site shows Passenger's error page:

We're sorry, but something went wrong.
Web application could not be started by the Phusion Passenger(R) application server.

cPanel runs Python apps with Phusion Passenger, which imports a file called passenger_wsgi.py from the app root and expects it to define application. If importing that file raises any exception, such as a missing package, a wrong settings module, or a syntax error, Passenger shows this generic page. The actual traceback is written to a log file you have to look up.

1. Find the traceback: check stderr.log in the app root, or set a log path in Setup Python App and reload.
2. Make passenger_wsgi.py import your Django WSGI app: from config.wsgi import application.
3. Install requirements inside the app's virtualenv using the source command cPanel shows.
4. Set DJANGO_SETTINGS_MODULE and other variables in the app's environment variables section.
5. Restart the app (button or touch tmp/restart.txt) after every change.

Step-by-step solution

1. Read the error log

In cPanel, open Setup Python App, edit the application, and note or set Passenger log file. Many hosts also write stderr.log in the application root. Through the terminal or File Manager:

tail -n 50 ~/myapp/stderr.log

You can also temporarily enable friendly error pages with PassengerFriendlyErrorPages on in .htaccess if your host allows it, which shows the traceback in the browser. Turn it off again afterwards.

2. Write passenger_wsgi.py correctly

cPanel creates a placeholder passenger_wsgi.py that returns "It works!". Replace it:

# ~/myapp/passenger_wsgi.py
import os
import sys

sys.path.insert(0, os.path.dirname(__file__))
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.production")

from config.wsgi import application  # noqa: E402

The application root in cPanel must be the directory that contains manage.py and this file. If your Django project package is not called config, use its real name.

3. Install packages in the app's virtualenv

Setup Python App shows a command at the top of the app page, like:

source /home/user/virtualenv/myapp/3.11/bin/activate && cd /home/user/myapp

Run it in the terminal, then pip install -r requirements.txt. Installing with the system pip or with --user puts packages where Passenger does not look. Packages that need compilation, such as mysqlclient, may fail on shared hosts without development headers; use pure-Python alternatives such as PyMySQL with pymysql.install_as_MySQLdb(), or wheels such as psycopg[binary].

4. Set environment variables

Add variables in the Environment variables section of the app: DJANGO_SETTINGS_MODULE, SECRET_KEY, DATABASE_URL, ALLOWED_HOSTS. Your SSH shell's exported variables do not reach Passenger. Click Save and restart.

5. Restart and serve static files

Passenger keeps app processes running between requests. After changes, restart from the cPanel page or:

mkdir -p ~/myapp/tmp && touch ~/myapp/tmp/restart.txt

Static files are not served by Django when DEBUG = False. On cPanel, either run collectstatic into a folder under public_html that Apache serves, or use WhiteNoise, which works well with Passenger.

Explanation

Passenger acts as the application server on cPanel. When a request arrives for an idle app, it spawns a Python process with the configured virtualenv's interpreter and imports passenger_wsgi.py. If the import raises, Passenger cannot obtain the application callable and serves its own error page, logging the details to the configured log file. Because the environment comes from cPanel's settings rather than your shell, missing variables and packages installed in the wrong place are the most common causes.

Edge cases / notes

• Python version. The app's Python version is fixed when you create it; changing it creates a new virtualenv that needs packages reinstalled.
• Resource limits. Shared hosts limit processes and memory (CloudLinux LVE). Heavy imports can exceed them and fail at startup.
• Long tasks. Passenger is not a place for background workers. Use the host's cron for scheduled commands; shared hosting rarely supports Celery.

Next steps

• Follow the full setup in Deploy Django on cPanel Shared Hosting.
• If CSS is missing after it starts, see Fix Static Files Not Loading in Django.
• Outgrowing shared hosting? Compare options in Best Hosting Options for Django Deployment.

FAQ

Where is the Passenger error log on cPanel?

At the path set as Passenger log file in Setup Python App, often stderr.log in the app root.

Why does the default "It works!" page show instead of Django?

The placeholder passenger_wsgi.py is still in place. Replace it with one that imports your Django WSGI application.

Do I need to restart after every change?

Yes, for Python code and settings. Touch tmp/restart.txt or use the Restart button.

Can I run Celery on cPanel?

Usually not. Shared hosts do not keep background processes running. Use cron for periodic jobs or move to a VPS.