Textbook of Python

A package is a way of organising related modules into a directory hierarchy. In the traditional (regular) form, a package is a directory containing an __init__.py file. The __init__.py runs when the package is imported and can define the package's public API, set up package-level variables, or be left empty. Sub-packages are directories nested inside a package, each with their own __init__.py.

Python 3.3 introduced namespace packages (PEP 420), which do not require __init__.py. Namespace packages can span multiple directories on sys.path, allowing independently distributed components to contribute to the same package name. In practice, regular packages (with __init__.py) remain far more common.

Packages enable structured import paths: from mypackage.subpackage.module import function. Absolute imports start from a top-level package on sys.path; relative imports use dots to navigate within the current package (e.g., from . import sibling or from ..parent import something). A well-organised package with a clear __init__.py and a consistent module structure makes large codebases navigable and maintainable.