When should I use a relative import in a small Python package?

A relative import locates another module by its position within the current package. One leading dot means the current package; additional dots refer to parent-package levels. Relative imports use the from ... import ... form. [S1][S2]

For example, imagine this layout:

shop_tools/
    __init__.py
    app.py
    formatting.py
    reports/
        __init__.py
        summary.py

In summary.py, this import refers to the formatting.py module in the parent package:

from ..formatting import format_total

The two dots move from shop_tools.reports up to shop_tools; formatting identifies the module there. This style is useful for expressing that a dependency is part of the same package. [S1][S2]

No. You can also write:

from shop_tools.formatting import format_total

Python supports both absolute and explicit relative imports for references within a package. [S1] The absolute form spells out the package path; the relative form emphasizes the relationship between modules within the package.

For a small package, choose the form that makes dependencies easiest to follow, then use it consistently for similar relationships. Relative imports can make nearby internal links clear. Absolute imports can make the package name and destination explicit. The Python documentation permits both and does not set one universal style preference. [S1]

A relative import depends on the importing module having package context. When a source file is run directly, its import metadata differs from package execution; the import reference notes that direct execution sets __main__.__spec__ to None. Using -m supplies module metadata when applicable. [S2]

For example, running summary.py directly may not provide the context needed for from ..formatting import format_total. Instead, run a package module with its module name from a location where the package is available, for example:

python -m shop_tools.reports.summary

The exact command depends on your layout and working directory. For an application’s main module, use absolute imports: the tutorial notes that a main module has no package context for relative imports. [S1]

A useful rule of thumb is: use relative imports for internal package links when the importing module has package context; use absolute imports for the application entry point. This is a practical choice, not a requirement that every package use one style. [S1]

With the example layout, shop_tools/reports/summary.py could contain:

from ..formatting import format_total


def make_summary(total):
    return format_total(total)

Then shop_tools/app.py, acting as the entry point, could use:

from shop_tools.reports.summary import make_summary

If a relative import fails, check both the import path and how the module was launched. Direct execution can lack package context, while -m supplies module metadata when applicable. [S2] The right style for other internal imports depends on which form makes your package easier to understand.