Package vs Module in Python

Python uses modules and packages to divide code into importable units. A module is usually one .py file; a package groups modules under a shared name. Knowing what each import binds helps you choose a structure and avoid assuming that a package import loads every submodule.

What Is a Python Module?

A module is an importable unit of Python code, commonly a .py file containing functions, classes, or values. For example, a file named greetings.py can define a reusable greet function. Other code can import the module and call greetings.greet(...). The module name comes from the filename without .py, and the function remains available as an attribute of that module.

Run this example:

from pathlib import Path
import sys
import tempfile

with tempfile.TemporaryDirectory() as folder:
    Path(folder, "greetings.py").write_text(
        'def greet(name):\n    return f"Hello, {name}!"\n', encoding="utf-8"
    )
    sys.path.insert(0, folder)
    import greetings
    print(greetings.greet("Ari"))

This creates the module in a temporary directory so the example runs as a single file without relying on another article file. The import binds the module name greetings; its function is accessed through that name.

What Is a Python Package?

A package groups related modules in a directory hierarchy. A regular package has an __init__.py file in its directory. That file runs when the package is imported and can contain initialization code or explicitly expose selected names. It can also be empty. The presence of __init__.py is not a universal requirement: Python namespace packages can span directories on the import path and omit that file.

A typical regular package might look like my_package/__init__.py, my_package/reader.py, and my_package/writer.py. The modules can hold focused pieces of functionality, while the package name provides a shared import path. A package can also contain subpackages, producing a deeper hierarchy when the project needs it.

How Python Imports Modules and Packages

An import loads the named module or package and binds names according to the import form. import greetings makes greetings available, while from greetings import greet binds greet directly. For a regular package, import my_package runs its __init__.py; it does not automatically import every module in the directory. To use a submodule, import it explicitly, for example from my_package import reader, or import a name that the package initializer deliberately exposes.

This distinction matters with dotted names. In import xml.etree, Python loads the named package path, and the name xml is bound in the current scope; use xml.etree to reach the subpackage. In from xml import etree, the name etree is bound directly. These forms can load related components but leave different names available to your code. A package initializer may provide a convenient public interface, but readers should not assume that every internal module is available after importing only the package.

Key Differences Between Modules and Packages

A module is typically a single file; a package is a directory-based namespace that can organize multiple modules and subpackages. A module provides a focused place for related definitions. A package groups those focused units and can define initialization behavior or a public interface. Their import paths reflect the structure: a standalone module might be imported as greetings, while a module inside a package might be imported as my_package.reader.

A package is not simply a module with a mandatory initializer. Regular packages use __init__.py, but namespace packages do not. Also, a package import does not promise that all child modules are loaded. Explicit imports make dependencies and available names easier to understand.

When to Use a Module or Package

Use a module when a small, focused set of functions or classes belongs together and does not need a hierarchy. Use a package when related responsibilities have grown into several modules, when subpackages help separate areas, or when you want a deliberate package-level interface. Start with a module when that is enough; split into a package when the organization improves navigation and reuse. Keep imports explicit so a reader can see where each name comes from.