Fix: ModuleNotFoundError: No module named ‘…’

The full message looks like this:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

It means: the Python interpreter that is running right now searched every folder on its import path and found no module with that name. The key words are “right now”. Your machine may have several Pythons (system, Homebrew, python.org installer, one per virtual environment), and each has its own packages.

Step 1: find out which Python is running

python -c "import sys; print(sys.executable)"
python -m pip --version    # shows which Python this pip belongs to

If the paths point to different installations, you have found the problem: the package went into one Python, your code runs in another.

Step 2: install into that exact interpreter

Activate your project’s virtual environment, then install with python -m pip so pip is guaranteed to match the interpreter:

source .venv/bin/activate      # Windows: .venv\Scripts\activate
python -m pip install requests
python main.py

If you do not have a virtual environment yet, create one first with python3 -m venv .venv. Plain pip install on a system Python is often blocked with externally-managed-environment on recent Linux and macOS setups anyway.

Other common causes

• Your editor uses another interpreter. In VS Code, run “Python: Select Interpreter” and choose the one inside .venv. PyCharm has the same setting under the project interpreter.
• The install name differs from the import name. You install beautifulsoup4 but import bs4; Pillow is imported as PIL, PyYAML as yaml, scikit-learn as sklearn, python-dotenv as dotenv. Check the package’s documentation.
• A typo or wrong case. Module names are case-sensitive on most systems: import Requests fails.
• Your own module is not on the path. If from utils import x fails, check where you run the command. Python adds the folder of the script you run (not your shell’s current folder) to the path. For a package layout, run modules from the project root with python -m mypackage.main instead of python mypackage/main.py.
• Tests cannot import your code. Run python -m pytest instead of pytest, or set pythonpath = ["."] under [tool.pytest.ini_options] in pyproject.toml.
• A cron job or service uses the system Python. Call the environment’s interpreter by full path, for example /home/me/project/.venv/bin/python /home/me/project/main.py.

A related but different error

If you named your own file after a library (say requests.py or random.py), the import succeeds but loads your file, and you get AttributeError or ImportError: cannot import name ... instead. Rename your file and delete any __pycache__ folder next to it.

Prevent it next time

1. Create a virtual environment for every project.
2. Always install with python -m pip install ....
3. Record dependencies in requirements.txt or pyproject.toml so a fresh environment can be rebuilt in one command.