Search code examples
pythonpython-3.xpython-importimporterror

How to import modules from parent directory/different package?

Working on a project that I cloned from GitHub, I came across the problem that import statements about modules in parent directories or different packages weren't recognized throwing ImportError. I posted this question about my specific occasion and continued researching about it.

Finally, I've come to a conclusion that I would like to share along with some resources for similar future problems.

Question

  • How to import a module from a parent directory or from a different package?
  • What is the proper way to do it?
Solution

  • Answer

    (or just some information about the question)

    According to python docs, importing a module works like this:

    When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations:

    • The directory containing the input script (or the current directory when no file is specified).
    • PYTHONPATH (a list of directory names, with the same syntax as the shell variable PATH).
    • The installation-dependent default.

    So, in the case that you simply want to import a module, e.g. my_pkg.my_module.py, which resides in a different location than the module importing it, my_pkg should be in the list that sys.path returns. For this to happen, there are (as far as I know) three ways:

    1. Modify PYTHONPATH variable. (as pointed out here) - Not preferred
    2. Modify sys.path at runtime. (as pointed out here) - Not preferred
    3. Having a setup.py file that resolves the import dependencies of your modules (and doing many other important things, too). - Proper way

    So, the first 2 ways above are generally considered not to be a good practice, but rather a temporary - bad solution that will lead to further problems during development process. The third one, though, is the best way to build a distributable, well-organized project that will be easily used by other people. Some of the benefits of setup.py file are illustrated here along with whole functionality of it.

    With a setup.py file you can clearly configure which are the packages that contain the modules to be imported to solve ImportError and do many other useful things about your project.

    Below are cited two very illustrative tutorials about how to use import statements and how to create a setup.py file, that I strongly recommend to take a look at:

    EDIT: Also, you can find plenty of information about how to configure, package and distribute your project here:

    Personally, I find it very useful in order to build a pretty good first setup.py file.