ModuleNotFoundError tells you that the import machinery could not resolve a requested module from its current search path. A package may exist on your computer and still be absent from the interpreter used by the IDE, scheduler, web server or notebook.
This guide is for Python ModuleNotFoundError in its stated software or device context. Capture the exact message and the operation that fails; the same keyword may have different meanings in another application. A reliable diagnosis identifies an observable difference, not just a plausible cause.
Recognize the symptoms
- `python app.py` raises `ModuleNotFoundError: No module named …`.
- A package imports in a terminal but fails in VS Code, Jupyter or production.
- The import started failing after changing virtual environments or Python versions.
Record the software version, device or server role, first failure time and any update or configuration change immediately before the incident. Compare whether the symptom affects one file, one user, one device or the entire service. These observations guide the safest first test.
Before making changes
Keep a restorable copy of important files, settings and credentials wherever the procedure might modify them. Use the original account, workflow and network for comparison. Perform one controlled change at a time, record the outcome, and undo changes that do not affect the failure.
If the action can create payments, data writes, account changes or destructive storage activity, do not retry it automatically. Confirm whether the previous operation already succeeded. Managed devices, production databases and service infrastructure require the owner’s authorization.
Step-by-Step Troubleshooting
Choose Beginner for reversible checks; Advanced covers evidence-based inspection, bounded changes and verification.
Read the missing import name precisely
Copy only the first complete missing-module name and the code location from the traceback. Distinguish a top-level third-party dependency from an internal project module or typo.
Identify the active interpreter
In the failing environment print `sys.executable` and Python version. IDEs, notebooks, containers and cron tasks can each use a different interpreter even on the same machine.
Inspect the same environment with pip
Use `python -m pip show PACKAGE` from that interpreter, replacing the placeholder with the actual distribution name. Some import names differ from package names; check official project documentation.
Activate or select the intended virtual environment
Select your project `.venv` in the IDE or activate it in the terminal, then retry the import. Prefer adding a pinned dependency to the project configuration over a global installation.
Compare interpreter and pip targets
Collect `sys.path`, `sys.executable`, `pip --version` and `python -m pip --version`. The concrete path differences reveal when bare pip installs to another Python.
python -c "import sys; print(sys.executable); print(sys.version)"python -m pip --versionpython -m pip show PACKAGE_NAME # replace PACKAGE_NAMETest shadowing and package layout
Check for project files such as `requests.py` or `json.py` that shadow real libraries. Review `pyproject.toml`, source directories and package `__init__.py` only where appropriate.
Inspect editable installs and deployment artifacts
In container/CI environments verify the requirements or lockfile are installed during the correct image/build stage. A local editable install may work on a developer PC but not in the shipped artifact.
Implement a reproducible environment fix
Install the correct package in a dedicated venv, record the version in a supported dependency file, and rerun the original script from the exact production invocation.
Diagnosis: identify the layer that is actually failing
Start with the evidence collected by the Beginner or Advanced tab, then compare the patterns below. A match is a working hypothesis; it is not proof until the original operation succeeds after a targeted, reversible change.
| Observed pattern | Evidence to inspect | Most useful next step |
|---|---|---|
| Terminal works, IDE fails | sys.executable in both contexts | Select the correct IDE interpreter. |
| pip reports installed, import fails | python -m pip show and python path | Install with the exact runtime Python. |
| Only one project/module fails | Package structure and local module names | Correct import/package layout without sys.path hacks. |
Common root causes to rule in or out
- A package was installed into a different Python interpreter or virtual environment.
- Distribution name and import name differ, or a local filename shadows the module.
- The package/project is not installed in the environment or its intended source layout is unavailable.
A recent change establishes a useful timeline but not causation on its own. Look for a repeatable relationship: does the failure follow a particular account, release, host, storage volume or workload? Compare an unaffected example under nearly identical conditions before choosing any broad repair.
What each result means
When the same problem reproduces on multiple independent devices or clients, focus on shared account, service or infrastructure conditions. When it follows one client, check its runtime, policies and local state. When only one particular operation fails, inspect that workload before reinstalling unrelated components.
If a command or diagnostic produces a different result than the article describes, stop and interpret that actual output. Examples are not meant to be executed blindly: identifiers, installation paths, network ports and supported options can vary by version and permissions.
How to verify the repair
Return to the exact action that produced Python ModuleNotFoundError. Repeat the safe test under the original account, environment and input conditions. An error disappearing after one reload is not enough if the underlying service still produces failures under normal use.
- Run the original command with the original interpreter.
- Confirm the module version and resolved import path.
- Rebuild a clean virtual environment or CI job from pinned dependencies.
Confirm that the adjacent feature still works and that the protective controls, data and settings kept during diagnosis remain intact. Record the exact effective change and keep the rollback instructions; a completed checklist is a tracking aid, not a guarantee that all failure conditions are gone.
Solution Checklist
If the error remains: rollback and escalation
Restore the previous requirements or environment selection if the new version creates conflicts. Remove only the specific incorrect dependency installed during testing.
Provide support with the redacted exact message, timestamps and timezone, version, environment, scope, relevant log excerpts and tests attempted. Do not include passwords, session cookies, license keys, complete private URLs or other secrets in public tickets.
How to prevent it from returning
- Use one virtual environment per project with pinned requirements.
- Invoke pip as `python -m pip` for the target interpreter.
- Test imports in CI using the same runtime as production.
Maintain a short incident note that distinguishes the confirmed cause from hypotheses that were tested and rejected. Update the note when a product release or platform policy changes the troubleshooting sequence.
Frequently asked questions
Why is a module installed but Python cannot find it?
The installer and runtime may point at different interpreters, or the import name may not equal the published distribution name.
Should I copy package folders into site-packages?
No. Use supported project packaging and virtual environments so dependency versions and locations remain reproducible.
Further reading: official documentation
Editorial note: vendor interfaces, error-code behavior and supported versions may change. Confirm the relevant product documentation before deploying a change to a production or managed system. This draft does not claim that every remedy was tested on the reader’s environment.
Disqus hosts the discussion. Comments load automatically as you approach this section and may use cookies.