SoftwareSideHustles
Debugging

How to Fix "ModuleNotFoundError: No module named ..." in Python (and "Cannot find module" in Node.js)

Why Python cannot find a module you just installed — the wrong interpreter, an inactive virtual environment, a package whose import name differs, or a file shadowing the library — and the equivalent fixes for Node.js.

By Software Side Hustles Editorial Team · Published · Updated · 5 min read

Quick answer: the package is almost always installed — just not into the Python interpreter that is running your code. Install it with the same interpreter you run: python -m pip install requests (not bare pip install), make sure your virtual environment is activated, and select that environment in your editor. If it still fails, check that the import name matches the package (pip install Pillow → import PIL) and that none of your own files has the same name as the module.

Step 1: confirm which Python is running

bash
python -c "import sys; print(sys.executable)"
python -m pip --version

Both should point at the same environment. If pip --version shows a different path from sys.executable, pip install has been installing packages somewhere your script never looks. That mismatch causes most "No module named" errors, especially on machines with several Pythons (system Python, Homebrew, pyenv, Conda, the Microsoft Store version on Windows).

The reliable habit is to always use:

bash
python -m pip install <package>

python -m pip runs pip for that exact interpreter. On Windows, py -m pip install <package> uses the Python launcher.

Step 2: use (and activate) a virtual environment

bash
python -m venv .venv
source .venv/bin/activate # macOS / Linux
.venv\Scripts\activate # Windows (PowerShell: .venv\Scripts\Activate.ps1)
python -m pip install -r requirements.txt

When the environment is active, python and pip refer to .venv. Opening a new terminal tab, a cron job or a systemd service does not inherit the activation — run those with the full path, e.g. /srv/app/.venv/bin/python app.py.

On recent Debian, Ubuntu and Homebrew Pythons, installing globally fails with error: externally-managed-environment (PEP 668). That is deliberate: create a virtual environment rather than forcing installs into the system Python.

Step 3: point your editor or notebook at the same environment

  • VS Code: Command Palette → "Python: Select Interpreter" → choose .venv. The interpreter is shown in the status bar.
  • PyCharm: Settings → Project → Python Interpreter.
  • Jupyter: a notebook kernel may be a different Python from your terminal. Install from inside the notebook with %pip install <package>, which targets the running kernel.

"It works in the terminal but not in the IDE" (or vice versa) is nearly always this step.

Step 4: check the import name

The name you pip install is not always the name you import:

pip installimport
PillowPIL
beautifulsoup4bs4
opencv-pythoncv2
scikit-learnsklearn
python-dotenvdotenv
PyYAMLyaml
google-cloud-storagegoogle.cloud.storage

Also watch capitalisation — module names are case-sensitive on Linux and in Docker images even if your Mac or Windows filesystem is not.

Step 5: make sure you are not shadowing the module

If you name your own file random.py, requests.py, email.py or test.py, Python imports your file instead of the library. The symptom is often not "No module named" but a confusing AttributeError or "cannot import name". Python 3.13+ now spells it out:

text
AttributeError: module 'random' has no attribute 'randint' (consider renaming
'/home/ada/project/random.py' since it has the same name as the standard library
module named 'random' and prevents importing that standard library module)

Rename the file — and delete any __pycache__ folder next to it.

Step 6: imports inside your own project

text
ModuleNotFoundError: No module named 'myapp'

when importing your own code usually means Python's search path does not include the project root. Typical fixes:

  • Run modules from the project root with -m: python -m myapp.cli rather than python myapp/cli.py.
  • Use a src/ layout and install your project in editable mode: python -m pip install -e ..
  • In tests, configure pythonpath for pytest (pythonpath = ["src"] in pyproject.toml) rather than editing sys.path in code.

ImportError: attempted relative import with no known parent package has the same cause: running a file inside a package as a script. Use python -m package.module.

Standard-library modules that disappeared

Some "missing" modules were removed from newer Pythons: distutils was removed in Python 3.12 (install setuptools, which provides a replacement), and several old modules such as imp, asynchat and cgi have been removed in recent releases. Upgrade the library that imports them, or pin an older Python while you migrate.

The Node.js equivalent: "Cannot find module"

text
Error: Cannot find module 'express'
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from /app/server.js

Checklist:

  1. Run npm install in the directory containing package.json — and run your app from that project, not a parent folder.
  2. Check the package is in dependencies, not only installed globally (npm install -g packages are not importable by projects).
  3. For relative imports in ES modules, include the file extension: import { x } from "./utils.js".
  4. In Docker, make sure node_modules is installed inside the image and not overwritten by a volume mount from your host.
  5. If all else fails, delete node_modules and the lockfile's install state: rm -rf node_modules && npm ci.

Frequently asked questions

I installed the package but still get ModuleNotFoundError. Why?

You installed it into a different interpreter. Compare python -c "import sys; print(sys.executable)" with python -m pip --version and use python -m pip install.

Should I use sudo pip install?

No. It modifies the system Python, can break operating-system tools and is blocked on many distributions. Use a virtual environment.

How do I fix it in Docker?

Install dependencies in the image (RUN python -m pip install -r requirements.txt) with the same Python that runs the app, and avoid mounting a host directory over the installed packages.

Where this skill pays off

Environment debugging is unglamorous but constant, and AI assistants often give generic advice ("reinstall the package") that misses the interpreter mismatch. Recognising the real cause quickly is valued in AI evaluation work and in tutoring alike — see side hustles for software engineers for ways to use it.

Cookies on this site

We use essential cookies to run the questionnaire, practice labs and sign-in. With your permission we'd also like to use analytics to understand which pages help people, and advertising cookies to measure our Google Ads. Rejecting never limits any feature. Cookie policy