Search guides

Fix Python that will not import

We'll confirm the error, check your Python and virtual environment, install with pip or set PYTHONPATH—or tell you when to escalate.

Troubleshooting · Devices & software
10–20 min
What you'll need
  • Python installed
  • pip (comes with Python)
Step 1 of 9

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Confirm the error, check Python and virtual environment, then install or fix the path.

  • Run your script or import. Read the full error—ModuleNotFoundError or ImportError shows the missing module name.
  • Good: You see the module name. Proceed to Check Python and package.
  • Bad: Different error—check the exact message; may be syntax or circular import.

Check Python and package

Goal: Confirm which Python you use and whether the package is installed.

  • Run which python (or where python on Windows) and python --version. Activate the correct virtual environment if you use one: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows).
  • Run pip list or pip show <package>. Check if the package is installed.
  • Good: You know the Python path and package status. Proceed to Install with pip or set PYTHONPATH.
  • Bad: Wrong Python or venv—activate the correct one and retry.

Install with pip or set PYTHONPATH

Goal: Install the missing package or add its path.

  • When the package is missing: run pip install <package>. For local projects: pip install -e . from the project root.
  • When the module is in a non-standard directory: set PYTHONPATH. Linux/Mac: export PYTHONPATH=/path/to/module:$PYTHONPATH. Windows: set PYTHONPATH=C:\path\to\module;%PYTHONPATH%.
  • Check for typos—module names are case-sensitive. The folder name must match the import.
  • Good: Package installed or path set. Retry the import.
  • Bad: pip install fails or import still fails—see When to escalate.

When to escalate

Escalate if:

  • pip install fails with dependency conflicts.
  • The package has no wheel for your platform.
  • You need a different Python version.

Provide the full error, python --version, pip list, and OS before escalating.

Verification

  • The import runs without ModuleNotFoundError.
  • pip list shows the package when it is from PyPI.
  • PYTHONPATH is set correctly when using local modules.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Check Python and venv which python, pip list, activate correct venv.
  2. pip install pip install <package> or pip install -e . for local.
  3. PYTHONPATH Set PYTHONPATH to the module directory.
  4. Recreate venv Delete venv, recreate, pip install -r requirements.txt.
  5. Escalate Provide full error, python --version, pip list, OS.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • Full error message (ModuleNotFoundError or ImportError)
  • python --version and which python
  • pip list output
  • Steps already tried

Do you see ModuleNotFoundError or ImportError?

Run your script or import. The error shows the missing module name.

Run your script. Read the full error. ModuleNotFoundError or ImportError: note the module name. Other error: check the exact message—may be syntax or a different issue. Confirm you should see the module name in the error.

Yes No

You can change your answer later.

Check the exact error

If not ModuleNotFoundError, the issue may be different. SyntaxError, AttributeError, or circular import have different fixes. Check the full traceback.

Done

Are you using the correct Python and virtual environment?

Run which python and pip list.

Run `which python` (or `where python` on Windows) and `pip list`. Wrong venv: activate the correct one. Correct venv: check if the package is in pip list. Confirm you should see the expected Python path and package list.

Yes No

You can change your answer later.

Activate the correct virtual environment

Activate the venv: `source venv/bin/activate` (Linux/Mac) or `venv\\Scripts\\activate` (Windows). Run `which python` again. Confirm you should see the venv path.

Done

Is the package in pip list?

pip list or pip show <package>

Run `pip list` or `pip show <package>`. Not in list: run pip install. In list: check PYTHONPATH or naming. Confirm you should see the package if installed.

Yes No

You can change your answer later.

Install with pip

Run `pip install <package>`. For local packages: `pip install -e .` from project root. Confirm you should see "Successfully installed".

Done

Is the module in a non-standard path?

Local modules or custom layout need PYTHONPATH.

If the module is in a custom directory: `export PYTHONPATH=/path/to/module:$PYTHONPATH` (Linux/Mac) or `set PYTHONPATH=C:\\path\\to\\module;%PYTHONPATH%` (Windows). Add the directory containing the module. Confirm you should see the import succeed.

Yes No

You can change your answer later.

Set PYTHONPATH and retry

Set PYTHONPATH to the directory containing the module. Retry the import. Confirm you should see the import succeed.

Done

Escalate

Provide full error, python --version, pip list, OS. Escalate if pip install fails, dependency conflicts, or package has no wheel for your platform.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why does Python say ModuleNotFoundError?
The module is not installed, not on PYTHONPATH, or you are using a different Python or virtual environment than where it was installed. Check pip list and which python.
How do I fix ModuleNotFoundError?
Install the package with pip install <package>. If it is a local module, add its directory to PYTHONPATH or run pip install -e . from the project root.
When should I escalate Python import errors?
If pip install fails, the package has conflicting dependencies, or you need a different Python version. Provide the full error, Python version, and pip list output.

Rate this guide

Was this helpful?

Continue to