Fix ModuleNotFoundError: No module named 'dotenv'

You installed the thing, you import it, and Python still says:

ModuleNotFoundError: No module named 'dotenv'

The frustrating part is that many people "installed dotenv" and still see this. That's because of a naming trap that catches almost everyone: the package you install and the module you import have different names, and there's a different package on PyPI literally called dotenv that is the wrong one.

Get the name right and 90% of these vanish. The rest are the classic ModuleNotFoundError cause — you installed it into a different Python than the one you're running. This guide fixes both, in that order.

Quick Answer

Install the correct package: pip install python-dotenv (not pip install dotenv — that's a different, wrong package). Then import it as from dotenv import load_dotenv. If it's still missing, you installed it into another interpreter, so run python -m pip install python-dotenv to target the exact Python you run.

TL;DR

• Package = python-dotenv, import = dotenv. The names differ by design.
• pip install dotenv is the wrong package — it won't fix the error.
• Still missing? You installed into a different interpreter.
• Use python -m pip install python-dotenv to target the right Python.
• In venvs: activate first, then install.
• In Jupyter/Colab: %pip install python-dotenv.
• Don't name a file dotenv.py — it shadows the package.

The Naming Trap

This is the single most common reason the error survives a "fix." On PyPI:

The distribution name (python-dotenv) and the import name (dotenv) are simply not the same string — which is common in Python (pip install beautifulsoup4 → import bs4, pip install opencv-python → import cv2). Memorize this one:

pip install python-dotenv          # ✅ correct
# pip install dotenv               # ❌ wrong package, don't

pip uninstall -y dotenv
pip install python-dotenv

Then the import works:

from dotenv import load_dotenv
load_dotenv()   # reads a .env file into environment variables

Still Missing? It's the Interpreter

If the name is right and it's still not found, you installed it into a different Python than the one running your script. This is the root cause of nearly every ModuleNotFoundError, not just this one.

Step 1: Confirm what's installed, and where

pip show python-dotenv        # is it installed? note the Location:
python -c "import sys; print(sys.executable)"   # which Python am I running?

If pip's Python and your script's sys.executable differ, that's the bug — the package is real, just in the wrong place.

Step 2: Install into the exact interpreter you run

The fix that removes all ambiguity is to invoke pip through the Python you use:

python -m pip install python-dotenv

• python -m pip runs pip inside this python, so the package lands where imports look for it.
• If you run python3, use python3 -m pip install python-dotenv.
• This is more reliable than a bare pip, whose interpreter can differ from python.

Step 3: Activate the virtual environment first

Installing before activating puts the package in the global interpreter, which the venv can't see:

# macOS / Linux
source venv/bin/activate
python -m pip install python-dotenv
 
# Windows (PowerShell)
venv\Scripts\Activate.ps1
python -m pip install python-dotenv

After activating, which python (macOS/Linux) or where python (Windows) should point inside the venv.

Step 4: Jupyter, Colab, and IDEs

Notebooks and IDEs often run a different interpreter than your terminal.

# In a Jupyter/Colab cell — %pip targets the kernel's interpreter
%pip install python-dotenv

• Jupyter/Colab: use %pip, then restart the kernel.
• VS Code / PyCharm: select the correct interpreter (the one where you installed it) in the interpreter picker, bottom-right / settings.

The Sneaky One: File Shadowing

If everything above is correct and it still fails, check for a file named dotenv.py in your project. Python searches your own directory first, so your file wins over the installed package:

# ❌ a local dotenv.py shadows the real package
ls dotenv.py
 
# ✅ rename it and clear caches
mv dotenv.py load_env.py
rm -rf __pycache__ dotenv.pyc

The same applies to a folder named dotenv/ in your project root.

Reproduce and Verify

Confirm the fix end to end:

import dotenv
print(dotenv.__version__)                    # e.g. 1.0.x — it's importable
 
from dotenv import load_dotenv
loaded = load_dotenv()                       # True if a .env was found
print("loaded:", loaded)

• dotenv.__version__ prints → the package is installed in this interpreter.
• load_dotenv() returns True when it finds a .env file.

Framework Notes

• Flask / FastAPI / Django: add python-dotenv to requirements.txt (or pyproject.toml) so deploys install it. Missing from requirements is the #1 "works locally, breaks in prod" cause.
• Docker: install it in the image, not just your host — RUN pip install python-dotenv (or via requirements). A missing entry means the container has no dotenv.
• Poetry / uv / Pipenv: use poetry add python-dotenv, uv add python-dotenv, or pipenv install python-dotenv so the lockfile records it.
• CI/CD: ensure the pipeline installs from the same requirements.txt your app expects; a partial cache can skip it.

Prevention

• Always pip install python-dotenv — never dotenv.
• Prefer python -m pip install to pin the interpreter.
• Pin python-dotenv in requirements.txt / lockfile.
• Activate the venv before installing.
• In notebooks, install with %pip.
• Never name a file or folder dotenv.
• Check sys.executable when a "installed" package won't import.

Troubleshooting Matrix

Related Guides

• Resolve ModuleNotFoundError: No module named 'cv2'
• Fix ImportError: cannot import name 'Mapping' from 'collections'
• Resolve ValueError: too many values to unpack
• Fix TypeError: Object of type datetime is not JSON serializable
• Setting up clean Python virtual environments

External References

• python-dotenv on PyPI
• python-dotenv documentation (GitHub)
• Python — Modules and the import system
• pip — Installing packages

FAQs

Is dotenv a real package on PyPI? Yes — and that's the trap. There is a separate package literally named dotenv, but it is not the one that provides load_dotenv. You want python-dotenv. Installing dotenv is the most common reason the error survives.

Why is the import name different from the install name? It's a common Python convention — the distribution name and the top-level module don't have to match. Other examples: beautifulsoup4 → bs4, Pillow → PIL, opencv-python → cv2. When in doubt, check the package's PyPI page for the import name.

How do I know which interpreter my code uses? import sys; print(sys.executable) prints the exact Python running your code. Compare it to pip show python-dotenv's Location. If they don't match, install with python -m pip.

Do I need python-dotenv in production? Only if you load .env files there. Many teams load real environment variables directly in production and use python-dotenv for local dev — but if your code calls load_dotenv() anywhere that runs in prod, the package must be installed there too.

Can I avoid the error by not using .env files? You can read environment variables with os.environ / os.getenv without python-dotenv at all. python-dotenv is a convenience for loading a .env file into os.environ; if you set real env vars another way, you don't need it.