Absolute vs Relative Imports

### Two ways to spell a module name Every `import` statement hands the import machinery a **module name** to resolve. An *absolute* import gives that name in full: `import app.core.config`, or `from app.core import config`. The machinery walks the dotted name left to right, importing `app`, then `app.core`, then `app.core.config`, checking the module cache in `sys.modules` at each level and otherwise asking the finders that search the interpreter's import roots on `sys.path`. Nothing about where the *importing* file sits on disk takes part in that lookup — an absolute name means the same thing written in any module of any package. An *explicit relative* import gives a name that begins with one or more dots: `from . import config`, `from .config import TIMEOUT`, `from ..core import io`. The dots are not filesystem navigation and have nothing to do with the current working directory. They are arithmetic on the importing module's own **package name**: one dot means "the package I am in", two dots mean "one package up", three dots two up, and so on. The machinery reads that package name from the module's metadata — `__package__`, which for a normally imported module is the same value the module's `__spec__` reports as its parent — joins it with whatever follows the dots, and then resolves the resulting absolute name exactly as if you had typed it out. `importlib.util.resolve_name` performs that one step in isolation, which makes it the easiest way to see the rule: ```python from importlib.util import resolve_name resolve_name(".config", package="app.services") # 'app.services.config' resolve_name("..core.io", package="app.services") # 'app.core.io' ``` ### Why the relative form exists Inside a package, most references are to siblings. Writing `from . import config` instead of `from app.services import config` keeps the package's own top-level name out of every file, so the package can be renamed, nested under another project, or vendored into an application tree without editing its internals. The relative form also states an intent that the absolute form cannot: *this module, the one shipped beside me* — never a same-named module that happens to be installed in the environment. ### The syntax restriction The relative form is legal only in a `from ... import ...` statement. `import .config` is a `SyntaxError`. The reason is mechanical: the plain `import` statement binds the *leftmost* component of the dotted name as a name in the current namespace (`import a.b.c` binds `a`), and a leading dot gives it nothing to bind. So there are exactly two relative shapes: `from . import config`, which imports the sibling *module* and binds the module object, and `from .config import TIMEOUT`, which imports that same module and then pulls one attribute out of it. Both go through identical name resolution; they differ only in what ends up bound in your namespace. ### The third form that no longer exists Python 2 had *implicit* relative imports. Inside `app/services/loader.py`, a bare `import config` searched the module's own package first and only then fell back to a top-level `config`. That rule made it possible to shadow a standard-library name for one package by accident, and made a bare import statement ambiguous to read. PEP 328 removed it. In Python 3, up to and including 3.14, a dot-free name is **always** absolute: `import config` inside `app.services` will never find `app/services/config.py`, and will raise `ModuleNotFoundError` unless a top-level `config` exists. Every relative import in modern Python is therefore explicit, marked by its dots. ### Where a relative import cannot work Because resolution is arithmetic on the package name, a module with no package name has nothing to compute from. That is the case for a file the interpreter runs as the top-level script (on 3.14 its `__package__` and `__spec__` are both `None`), for code typed at the REPL, and for a module imported as a top-level module rather than as part of a package (its `__package__` is the empty string). All three raise `ImportError: attempted relative import with no known parent package`. A separate case is climbing too far: `from ...util import x` inside `app.services` counts up past the top-level package, which raises `ImportError: attempted relative import beyond top-level package`. Neither error consults the filesystem — the machinery never looks at a parent directory to see whether one "could" be a package. ### Reading them in review A useful summary: an absolute import is a coordinate; a relative import is a direction. The coordinate is unambiguous to a reader, greppable across a repository, and unaffected by where the file lives inside its package. The direction is shorter, survives a rename of the enclosing package, and pins the reference to the copy of the package the module ships in — but it changes meaning the moment the file moves to a different depth, and it fails outright in a module that was not imported as part of a package.