Runtime Diagnostics
Python ModuleNotFoundError Debugging Guide
Resolve Python ModuleNotFoundError by proving the active interpreter, environment, import path, package name and project layout before reinstalling dependencies. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Identify the interpreter | Compare the executable used by the shell, IDE, test runner and service. |
| Check package presence | Query the same interpreter with python -m pip rather than a separate pip command. |
| Inspect import resolution | Review sys.path, package directories and working directory without adding broad path hacks. |
| Validate project packaging | Confirm package markers, editable installs and module names match the repository layout. |
Starter snippet
python -c "import sys; print(sys.executable); print(*sys.path, sep='\n')"Review checks
- Reproduce in a fresh virtual environment.
- Use python -m pip for installs and inspection.
- Check case-sensitive file names on Linux.
- Keep application modules distinct from dependency names.
Common mistakes
- Installing globally until the import works.
- Appending repository paths in production code.
- Naming a local file after a standard or third-party module.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Python Virtualenv Debugging Guide, Python Pip Requirements Guide, Python Runtime Guide.