How do I troubleshoot "ModuleNotFound" errors

Question

I often run into issues where my own modules are not found in python, and while I've been addressing them on a case-by-case basis, I don't really feel like I know how to actually troubleshoot them. It seems like such a vague error compared to anything else. What should the order of operations be when checking encountering this?

If it's an installed package obviously it's prudent to check that it has actually been installed and that the virtual environment is activated, if one is being used. It's certainly also good to verify that the spelling is correct.

After these two steps however, I often feel lost. Is there a way to check where python is looking for these modules? When using imports, does it being a module (with a __init__.py) make a difference? Are there any other tools or best practices I can use to avoid these problems?

I'm most interested in the methodology and the troubleshooting approach I can take here.

Answer 1

If you get the ModuleNotFoundError when trying to import a module of your own, then the problem is one of three things:

1. The module is in the wrong location. Fix this error by moving it to the correct location.

2. The import is incorrectly written to look in the wrong location. Fix this error by writing the import correctly.

3. You expected the module search path to contain the module, but it does not. Fix this by updating the module search path, typically by adding one or more directories to sys.path or by defining a PYTHONPATH environment variable. (Usually the other two options are preferred. It's unusual that you would need to do this.)