How to Solve "ModuleNotFoundError: No module named 'django'" in Python

The error ModuleNotFoundError: No module named 'django' indicates that Python can not find the Django framework. This typically happens because Django isn't installed in your current Python environment, you're using the wrong environment, or there's a configuration issue.

This guide provides a complete walkthrough for installing Django, troubleshooting common problems, and configuring your development environment (VS Code, PyCharm, Jupyter, Anaconda).

Installing Django (The Basic Solution)

Install Django using pip, Python's package installer:

pip install django

• Multiple Python Versions: If you have multiple Python versions, use pip3 (or pip3.9, pip3.10, etc.):

  pip3 install django

• Permissions Errors: If you encounter permissions issues:

  sudo pip3 install django   # Linux/macOS (use with caution!)
  pip install django --user  # Install for the current user

  Using a virtual environment (explained below) is the best way to avoid permission problems.

• python -m pip: If pip isn't directly accessible:

  python -m pip install django  # Or python3 -m pip or py -m pip

• Anaconda: If you're using Anaconda, it's generally best to use conda:

  conda install -c anaconda django

Verifying the Installation

After installing, verify it's working with a simple check:

import django

print(django.__version__) # Print the installed version

If this runs without a ModuleNotFoundError, Django is installed. If you still see the error, continue to troubleshooting.

Troubleshooting ModuleNotFoundError

Virtual Environments (Essential)

Always use virtual environments for your Python projects. This is the most important troubleshooting step:

1. Create: python3 -m venv venv (or python -m venv venv , py -m venv venv)
2. Activate:
   • Linux/macOS: source venv/bin/activate
   • Windows (cmd): venv\Scripts\activate.bat
   • Windows (PowerShell): venv\Scripts\Activate.ps1
     • If you get "Activate.ps1 can not be loaded because running scripts is disabled" error, run:

       Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
     Then try activating again.
3. Install: pip install django (inside the activated environment).

Your terminal prompt will change (e.g., (venv) $).

Multiple Python Versions:

• Check: python --version (or python3 --version)
• Correct pip: Use the pip (pip3, pip3.x, python -m pip) that corresponds to your intended Python version.

IDE Configuration (VS Code, PyCharm)**

Configure your IDE to use the correct interpreter/environment.

• VS Code:

  1. Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
  2. "Python: Select Interpreter".
  3. Choose the correct environment.

• PyCharm:

  1. "File" -> "Settings" -> "Project" -> "Python Interpreter".
  2. Select/add the correct interpreter.

Jupyter Notebook

Install within a notebook cell:

!pip install django

Ensure your Jupyter kernel uses the correct environment.

Naming Conflicts

Do not name your files/directories django.py or django.

Reinstalling Django

As a last resort:

pip uninstall django
pip install django

Installation Instructions for Specific Environments

Windows:

• Open Command Prompt or PowerShell.
• Use pip install django (or py -m pip install django).

macOS / Linux:

• Open your Terminal
• Use pip3 install django

Anaconda:

• Use conda install -c anaconda django

Jupyter Notebook (within a cell):

!pip install django

Handling "Import 'django' could not be resolved" (Pylance - VS Code)

• Correct Interpreter: Use "Python: Select Interpreter" in VS Code.
• Restart VS Code: Try restarting.
• Ignore (Last Resort): import django # type: ignore

Conclusion

The ModuleNotFoundError: No module named 'django' error is almost always resolved by installing Django in the correct Python environment and ensuring that the environment is correctly activated.

The key is:

• using virtual environments
• checking Python versions and IDE configurations.

By following these steps, you'll be able to successfully install and use Django in your Python projects.