Fix ModuleNotFoundError: No module named 'django_heroku'

Deploying a Django app to Heroku is exciting. But you may see a scary error: ModuleNotFoundError. This error stops your app from running. It happens when Python cannot find a required package. This guide will help you fix it fast.

We will cover common causes and solutions. You will learn how to check your environment, update files, and test locally. Each step is simple and beginner-friendly.

Why Does This Error Happen?

Heroku uses a file called requirements.txt to install packages. If a package is missing from this file, you get ModuleNotFoundError. Another common cause is using a package that is not in the default Python environment.

Sometimes, the error occurs because you forgot to push the updated requirements.txt to Heroku. Or, you may have installed a package locally but not added it to the file.

For a deeper understanding of Python import errors, check out our guide on How To Solve ModuleNotFoundError: No module named in Python.

Step 1: Check Your requirements.txt

First, log into your Heroku app. Run this command to see the current environment:

heroku run pip list

Look for the missing module. For example, if the error says ModuleNotFoundError: No module named 'psycopg2', then psycopg2 is missing.

Now, check your local requirements.txt file. It should list every package your app needs. If a package is missing, add it.

To generate an up-to-date requirements file, run:

pip freeze > requirements.txt

This command writes all installed packages to the file. Make sure you are in the right virtual environment.

After updating, commit the file and push to Heroku:

git add requirements.txt
git commit -m "Update requirements"
git push heroku main

Step 2: Verify Your Virtual Environment

Sometimes, you install packages globally instead of in your virtual environment. Heroku uses the environment defined by your requirements.txt. If a package is not in the virtual env, it will not be installed.

Activate your virtual environment locally:

source venv/bin/activate  # On Linux/Mac
venv\Scripts\activate     # On Windows

Then install the missing package:

pip install psycopg2-binary

After installation, run pip freeze > requirements.txt again. This ensures the package is recorded.

Step 3: Check for Buildpack Issues

Heroku uses buildpacks to set up the environment. If you are using a database like PostgreSQL, you need the heroku/python buildpack. Sometimes, missing system libraries cause ModuleNotFoundError.

To check your buildpacks, run:

heroku buildpacks

If you see only one buildpack, add the Python one:

heroku buildpacks:set heroku/python

For Django apps with PostgreSQL, you may also need the heroku/postgresql add-on. This add-on installs the necessary system packages.

Step 4: Update Your Django Settings

Your settings.py file may reference a package that is not installed. For example, using django-cors-headers without adding it to requirements will cause an error.

Check your INSTALLED_APPS list. Remove any apps you are not using. Then, ensure all listed apps are in requirements.txt.

Here is a simple example of a settings.py section:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',          # Requires djangorestframework
    'corsheaders',             # Requires django-cors-headers
    'myapp',
]

If you see ModuleNotFoundError: No module named 'rest_framework', then djangorestframework is missing from requirements.txt.

Step 5: Test Locally with Heroku Environment

Use the heroku local command to test your app locally. This mimics the Heroku environment.

heroku local web

If you get the same error locally, you can debug faster. Install the missing package and update requirements.

For example, if the error is ModuleNotFoundError: No module named 'gunicorn', install it:

pip install gunicorn
pip freeze > requirements.txt

Then test again. This step catches issues before pushing to Heroku.

Step 6: Clear Heroku Cache

Sometimes, Heroku caches old packages. Clearing the cache forces a fresh install.

To clear the cache, run:

heroku plugins:install heroku-repo
heroku repo:purge_cache -a your-app-name

Replace your-app-name with your actual app name. Then redeploy:

git commit --allow-empty -m "Clear cache"
git push heroku main

This often fixes stubborn ModuleNotFoundError issues.

Step 7: Check for Typo in Package Name

A simple typo in requirements.txt can cause the error. For example, writing django-cors-header instead of django-cors-headers will fail.

Double-check the exact package name on PyPI. Use pip show package-name to verify the installed version.

If you are unsure, search for the package online. The official name is always correct.

Step 8: Use a Procfile Correctly

Your Procfile tells Heroku how to run your app. If it references a module that is not installed, you get ModuleNotFoundError.

Common Procfile examples:

web: gunicorn myproject.wsgi --log-file -

Make sure gunicorn is in requirements.txt. Also, ensure the WSGI path is correct. For a Django project named myproject, the path is myproject.wsgi.

Conclusion

The Django Heroku ModuleNotFoundError is usually easy to fix. Start by checking your requirements.txt file. Ensure every package your app uses is listed there. Then verify your virtual environment and buildpacks. Test locally with heroku local to catch errors early. Finally, clear the Heroku cache if needed.

Remember to always update requirements.txt after adding a new package. This simple habit prevents most deployment errors. For more help, refer to our guide on How To Solve ModuleNotFoundError: No module named in Python. With these steps, your Django app will run smoothly on Heroku.