Diagnose Python interpreter and virtual-environment problems

Begin with the exact executable

A successful pip install does not prove the process running your program can import the package. Your shell, editor and notebook can select different Python installations. Record the command that starts the failing program before changing anything. Reinstalling Python is rarely the most informative first experiment.

Run python -c "import sys; print(sys.executable); print(sys.version)" in the terminal used for the failure. Run equivalent code through the editor’s Run action. If the paths differ, investigate interpreter selection. A browser runtime is another interpreter, not your laptop’s environment.

Match installer to interpreter

Use python -m pip --version to identify the installer associated with the executable. Prefer python -m pip install package while diagnosing ambiguity. On Windows, py -0p lists launcher-managed installations; python3 may be the appropriate command elsewhere. Adapt commands to the interpreter you actually found.

Create a disposable environment with python -m venv .venv. Activation changes command lookup; it is convenient, not magic. You can invoke the environment’s executable directly. Do not commit that directory or copy it between operating systems. Keep the old environment until the replacement is verified.

Classify the failure

ModuleNotFoundError can mean the package is absent, the interpreter is wrong or the import name differs from the distribution name. A partially initialized module error may come from naming a local file after a package, such as json.py. Read the traceback and inspect filenames before reinstalling everything.

Native-extension errors can involve an unsupported Python version or architecture. Check the package’s documentation and reproduce with a clean environment. Do not execute arbitrary installation commands simply because an error page recommends them.

Practice with controlled evidence

The companion runs real Python in your browser and tests a diagnostic function using synthetic paths. It does not inspect your computer, create a virtual environment or install packages. Expected results distinguish interpreter mismatch, missing dependency and consistent setup.

Compare the running and installer paths first. A package list from a different interpreter is irrelevant to the failing process. Then check whether the package is installed. Change the fixture paths yourself and predict the answer before running again.

Keep the evidence comparable

In a local terminal, compare python --version with python -c "import sys; print(sys.executable)" before installing anything. Then invoke pip through that same interpreter with python -m pip --version. On Windows the py launcher can select a different installation from a command named python; record which command the editor actually runs. An editor restart or terminal reactivation may be necessary after changing environments.

The browser exercise uses controlled paths, so it cannot inspect your computer. Predict which path belongs to the selected environment, run the check, and explain the mismatch in one sentence. A successful import in Pyodide does not prove a package is installed in your laptop environment. Keep those two observations separate in your debugging notes.

Try it yourself

def diagnose(running, installer, installed):
    return "ready"

print(diagnose("env-a/python", "env-b/python", True))

Enable JavaScript for this interactive activity. You can read all lesson explanations above without it.