Python imports

  1. Identify clearly what you want your top level modules and packages to be.

  2. Make all imports absolute.

  3. Either:

    • make your project a real installable project, so that those top level modules and packages are installed in the environment’s site-packages directory;

    • or make sure that the current working directory is the one containing the top level modules and packages.

  4. Make sure to call your code via the executable module method instead of the script method:

    • DO

      • path/to/pythonX.Y -m toplevelpackage.module

      • path/to/pythonX.Y -m toplevelmodule

      • path/to/pythonX.Y -m toplevelpackage.subpackage (assuming there is a toplevelpackage/subpackage/__main__.py file)

    • DON’T

      • path/to/pythonX.Y toplevelpackage/module.py

      • path/to/pythonX.Y toplevelmodule.py

  5. Later on, once it all works well and everything is under control, you might decide to change some or all imports to relative. (If things are done right, I believe it could be possible to make it so that it is possible to call the executable modules from any level within the directory structure as the current working directory.)

References: