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.)

Answer 2

Three potential problems that might cause it:

1. Most times, It might be not having a src/ folder in your projects, it is advisable you do if you don't, You should also have a project dependency management system, I would recommend poetry.

2. Secondly, python interpreter, if you use a unix machine/mac you can cd to your env/folder, where python lives -> after you run env-command to create a virtual env, it helps point installed modules to where python lives. You should also practice using full path/ as against relative import paths , which might give attempted relative import with no known parent package.

   run:

   export PYTHONPATH=${PYTHONPATH}:${env/bin/python}/
   

3. If you don't have a main.py file in your folder and you want to run a module or file using the if __name__ == "__main__" to check if your code works, you can run this command on your terminal

   python3 -m src.module.file_name
   

NB: In most cases, if you print(__package__), you get None. That is because you don't have a parent package or a main.py file