Understanding Python Imports: Absolute vs Relative Imports

Python’s import mechanism allows you to use code from other modules and packages. However, understanding how imports work can be tricky, especially when dealing with relative imports. In this tutorial, we’ll cover the basics of absolute and relative imports in Python.

Absolute Imports

Absolute imports are used to import modules or packages that are available on the sys.path. The sys.path is a list of directories where Python looks for modules to import. When you use an absolute import, Python searches for the module in all the directories listed in sys.path.

For example, consider the following project structure:

myproject/
    mypackage/
        __init__.py
        a.py
    anotherpackage/
        __init__.py
        b.py

To import b from anotherpackage in a, you can use an absolute import:

# in module a.py
import anotherpackage.b

Relative Imports

Relative imports are used to import modules or packages that are relative to the current module. To use relative imports, your module must be part of a package.

For example, consider the following project structure:

myproject/
    mypackage/
        __init__.py
        a.py
        b.py

To import b from a, you can use a relative import:

# in module a.py
from . import b

Note the dot (.) before b. This tells Python to look for b in the same package as a.

Running Scripts vs Importing Modules

When running a script directly (e.g., python myscript.py), the script is treated as the __main__ module. In this case, relative imports won’t work because the __main__ module is not part of a package.

However, when importing a module from another module or package, relative imports will work because the imported module is part of a package.

To demonstrate this, let’s consider an example:

myproject/
    main.py
    mypackage/
        __init__.py
        a.py
        b.py

In a.py, we have:

# in module a.py
print(__name__)

try:
    from . import b
except ImportError:
    print('Relative import failed')

try:
    import b
except ModuleNotFoundError:
    print('Absolute import failed')

Running main.py which imports mypackage.a, we get:

$ python main.py
mypackage.a
True
Absolute import failed

However, running a.py directly, we get:

$ python mypackage/a.py
__main__
Relative import failed
True

As you can see, relative imports work when importing modules from other packages, but not when running scripts directly.

Setting PYTHONPATH

Another way to resolve import issues is by setting the PYTHONPATH environment variable. This tells Python where to look for modules and packages in addition to the default locations.

To set PYTHONPATH, you can use:

export PYTHONPATH=$PYTHONPATH:/path/to/your/project/

on Unix-like systems or:

set PYTHONPATH=%PYTHONPATH%;C:\path\to\your\project\

on Windows.

By setting PYTHONPATH, you can make your project’s modules and packages available for import without having to modify the sys.path manually.

Best Practices

To avoid import issues, follow these best practices:

• Use absolute imports whenever possible.
• Avoid using implicit relative imports (i.e., import b instead of from . import b).
• Set PYTHONPATH if you need to make your project’s modules and packages available for import.
• Use the __future__.absolute_import module to ensure compatibility with Python 2 and 3.

By following these guidelines, you can write robust and maintainable code that avoids common import issues.