Python / Editorial solution guide

Resolve ModuleNotFoundError and interpreter mismatches

Identify the interpreter actually running the program, distinguish import names from distributions, and repair one project environment without changing the system installation.

About 4 min readContent reviewed

Read-only knowledge base · No public comments

Recognize the symptoms

An import raises ModuleNotFoundError even though a package manager reports that a dependency is installed. The same file may work in one terminal and fail in an editor or notebook.

The exception’s missing name may be a transitive dependency rather than the package named in your source. Preserve the complete traceback and its final missing name first.

Understand the likely causes

  • Installation and execution can target different interpreters or virtual environments. A distribution name can also differ from its import package name, so guessing an installation command from the missing token is unreliable.
  • Local names can shadow standard or third-party modules. A broken invocation of a package, or a missing dependency within an otherwise installed distribution, requires a different repair from installing the top-level package again.

1. Identify the executing interpreter

Run a small diagnostic in the same launch context as the failure: the editor’s selected interpreter, the notebook kernel, or the terminal command. Record sys.executable, the major and minor version, sys.prefix, and sys.base_prefix. In a conventional venv, differing prefixes indicate that environment is active for this process. Compare the facts from the failing and working contexts. Do not assume that an activated terminal changes an already running editor or notebook kernel.

python Interpreter facts 
import sys

print(sys.executable)
print(sys.version_info[:2])
print(sys.prefix)
print(sys.base_prefix)

Paths and minor versions vary by machine; compare them locally rather than expecting a fixed output. This code reads interpreter state and does not install anything.

2. Distinguish naming, shadowing, and dependency failure

Read the last missing name in the traceback and compare it with the dependency’s official installation documentation. Verify the intended distribution’s import spelling before considering installation. For a known top-level name, importlib.util.find_spec can check whether the current interpreter can locate a specification; use a literal known name during diagnosis, since probing dotted names may import their parents. Review project filenames such as json.py or typing.py and inspect the origin of modules that do load. Rename a collision deliberately, then restart the process.

python Check a known standard-library module 
import importlib.util

spec = importlib.util.find_spec("json")
print(spec is not None)
Expected output
True

This checks availability in the current interpreter without assuming a third-party dependency or printing a private filesystem path.

3. Align one project environment

Select the interpreter required by the project. If no project environment exists, creating a new .venv with that interpreter is a local setup change, separate from this read-only diagnosis. Configure the editor or kernel to use its executable. Manage dependencies through that exact interpreter’s -m pip, following the project’s reviewed dependency file and official installation guidance. The command below only asks the selected interpreter which pip it owns; it does not install or upgrade packages. Do not solve the mismatch with a system-wide installation or by copying another machine’s environment directory. Restart long-lived processes after changing interpreter selection.

bash Inspect the selected interpreter’s package manager 
python -m pip --version

Use the project’s actual interpreter command in place of python when necessary. The output contains an environment-dependent installation path.

4. Verify the repair in the original launch context

Repeat the minimal import with the same editor run action or terminal invocation that originally failed. Confirm that its interpreter facts now agree with the chosen project environment. If the top-level package imports but a nested dependency still fails, inspect that new traceback instead of declaring success. For package-relative imports, use the project’s documented module entry point, commonly python -m package.module, from its intended location. A successful import in a different shell is useful comparison evidence but does not establish that the original application uses the repaired environment.

Verify the fix

The original launch context uses the intended executable and successfully imports the required module. Its origin belongs to the expected library or project location, and the application’s focused startup check passes without a new missing dependency.

Retain the before-and-after interpreter facts locally. If only a diagnostic shell succeeds, the editor or kernel selection remains unresolved.

Keep it from recurring

  • Record supported Python versions and dependencies, keep virtual environments reproducible, and configure editor interpreter selection explicitly. Use interpreter-qualified package management and avoid module filenames that collide with libraries.
  • A virtual environment isolates dependencies; it is not a security sandbox and does not justify installing an unreviewed package merely because its name resembles an error.

Official references