Skip to main content

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

The ModuleNotFoundError: No module named 'dotenv' error in Python means that you're trying to use the python-dotenv library, which is used to load environment variables from a .env file, but Python can't find it. This usually happens because:

  • The python-dotenv package is not installed.
  • It's installed in the wrong Python environment (e.g., a different virtual environment or a different Python version).
  • Your IDE/editor is configured to use a different Python interpreter.
  • You have a naming conflict.

This guide will walk you through installing python-dotenv, troubleshooting common issues, and using it correctly.

Installing python-dotenv​

The correct way to install python-dotenv is using pip:

pip install python-dotenv

  • Multiple Python Versions: If you have multiple Python versions installed, you might need to use pip3:

    pip3 install python-dotenv

  • Permissions Errors: If you get a permissions error:

    sudo pip3 install python-dotenv  # Linux/macOS (use with caution)
    pip install python-dotenv --user # Install for current user only

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

    python -m pip install python-dotenv  # Or python3 -m pip, py -m pip

  • Using Conda: If you are using Anaconda, use the following command:

    conda install -c conda-forge python-dotenv

Verifying the Installation​

After installation, verify it's working with a simple example:

Create a .env file in the same directory as your Python script:

DOMAIN=example.com
[email protected]

Create a main.py file:

import os
from dotenv import load_dotenv

load_dotenv()  # Load environment variables from .env

print(os.environ.get('DOMAIN'))       # Access environment variables
print(os.environ.get('ADMIN_EMAIL'))

Output:

example.com
[email protected]

Run this script (python main.py). If it prints the values from your .env file without a ModuleNotFoundError, python-dotenv is correctly installed.

Troubleshooting ModuleNotFoundError​

If you still get the error after installation, follow these steps:

Virtual Environments (Essential)​

Always use virtual environments. They are the single most important thing you can do to avoid dependency conflicts.

  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.exe): venv\Scripts\activate.bat
    • Windows (PowerShell): venv\Scripts\Activate.ps1
      • If you get a PowerShell error about script execution, run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

  3. Install: pip install python-dotenv (inside the activated environment).

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

Multiple Python Versions​

Make sure you installed python-dotenv for the correct Python version. Check your version (python --version) and use the matching pip.

IDE Configuration (VS Code, PyCharm)​

Your IDE needs to be configured to use the correct interpreter/environment.

Jupyter Notebook​

Install within a notebook cell using:

!pip install python-dotenv

Ensure your Jupyter kernel uses the correct environment.

Naming Conflicts​

Never name your files dotenv.py.

Reinstalling python-dotenv​

pip uninstall python-dotenv
pip install python-dotenv

4. Installation Instructions for Specific Environments

Windows:​

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

macOS / Linux:​

  • Open your Terminal
  • Use pip3 install python-dotenv

Anaconda:​

  • Use conda install -c conda-forge python-dotenv

Jupyter Notebook (within a cell):​

!pip install python-dotenv

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

  • Select the correct interpreter.
  • Restart VS Code.
  • If you are sure that your code and interpreter are set correctly, you can use a comment # type: ignore to temporarily hide the Pylance warnings.
from dotenv import load_dotenv # type: ignore

Conclusion​

The ModuleNotFoundError: No module named 'dotenv' error is easily fixed by installing the python-dotenv package in the correct Python environment.

Using virtual environments is essential for good dependency management.

This guide provides a complete guide to installing and troubleshooting python-dotenv, ensuring you can use environment variables in your projects.

Table of Contents