What is the difference between a module and a package in Python?
A module is a single file; a package is a directory that groups modules
A module is any file that Python can import as a unit, usually a .py file but also .pyc, .so, or .pyd extensions. A package is a directory that groups related modules. Historically a package required an init.py file, which runs on import and defines the package namespace. Since Python 3.3, PEP 420 introduced namespace packages, which are directories without init.py that can be split across multiple locations on sys.path. The distinction matters for import syntax: importing a module runs its top-level code once and caches it in sys.modules. Importing a package runs its init.py and exposes its submodules and subpackages. A package can contain subpackages, forming a hierarchy. In practice, you choose a module for a small self-contained unit and a package when you need a namespace, submodules, or distribution as a single installable unit.
- 1
Module: a single file such as utils.py. Import with import utils or from utils import helper.
- 2
Regular package: a directory with init.py, for example mypkg/init.py. Submodules are mypkg.core, mypkg.io.
- 3
Namespace package: a directory without init.py. Useful for splitting a namespace across distributions.
- 4
init.py runs on import and can define all, version, and package-level initialization.
- 5
Trade-off: packages add structure and namespacing but require careful init.py design to avoid slow imports or import side effects.
- 6
Common mistake: assuming a directory is importable without init.py. In Python 2 it was not a package; in Python 3 it becomes a namespace package only if no regular package or module shadows it.
- 7
Common mistake: putting heavy imports or side effects in init.py, which slows every import of any submodule.
- 8
Version note: PEP 420 namespace packages are Python 3.3+. Regular packages with init.py work in all versions and remain the explicit choice for most projects.
Scenario Questions
0-2 years experience
- 1How do you import a function from a file named helpers.py?
- 2What file makes a directory a regular package?
2-5 years experience
- 1You have a directory without __init__.py and imports work in Python 3 but not in Python 2. Why?
- 2Your package __init__.py imports every submodule and import time is slow. How do you fix it?
5-8 years experience
- 1You need to distribute a namespace that multiple teams contribute to. How do you structure it with namespace packages?
- 2You are splitting a monolith into packages. How do you decide the package boundaries and __init__.py contents?
8+ years experience
- 1Design a package layout for a platform with shared libraries, plugins, and optional extras, keeping import time and dependency coupling under control.
- 2Explain how namespace packages, regular packages, and __init__.py interact when multiple distributions share a top-level name.
Follow-up Questions
- What is the difference between a regular package and a namespace package?
- Why is it a bad idea to put heavy imports in __init__.py?