Bird
Raised Fist0
PythonComparisonBeginner · 4 min read

Module vs Package in Python: Key Differences and Usage

In Python, a module is a single file containing Python code, while a package is a folder that contains multiple modules and a special __init__.py file to group them. Modules help organize code in one file, and packages organize multiple modules into a directory structure.
⚖️

Quick Comparison

Here is a quick side-by-side comparison of Python modules and packages to understand their main differences.

FactorModulePackage
DefinitionA single Python file (.py) with codeA directory with multiple modules and an __init__.py file
StructureOne fileFolder containing multiple files and subfolders
PurposeOrganize code in one fileOrganize related modules together
Import styleimport module_nameimport package_name.module_name
ContainsFunctions, classes, variablesMultiple modules and sub-packages
Examplemath.pynumpy/ (folder with many modules)
⚖️

Key Differences

A module in Python is simply a file that contains Python code such as functions, classes, or variables. It helps you keep your code organized by splitting it into separate files. You can import a module directly by its filename without the .py extension.

A package is a way to organize multiple related modules into a folder. This folder must contain a special file named __init__.py (which can be empty) to tell Python that this folder is a package. Packages allow you to create a hierarchy of modules and sub-packages, making large projects easier to manage.

When you import a module, you get access to the code inside that single file. When you import from a package, you specify the package and the module inside it, which helps avoid name conflicts and keeps code modular. Packages are essential for distributing libraries and frameworks.

⚖️

Code Comparison

Here is an example showing how to create and use a simple module in Python.

python
## mymodule.py

def greet(name):
    return f"Hello, {name}!"


# main.py
import mymodule

print(mymodule.greet('Alice'))
Output
Hello, Alice!
↔️

Package Equivalent

Now, the same functionality organized as a package with a module inside it.

python
# Directory structure:
# mypackage/
# ├── __init__.py
# └── greetings.py

# mypackage/greetings.py

def greet(name):
    return f"Hello, {name}!"


# main.py
from mypackage import greetings

print(greetings.greet('Alice'))
Output
Hello, Alice!
🎯

When to Use Which

Choose a module when you have a small set of related functions or classes that fit well in a single file. Modules are perfect for simple scripts or small utilities.

Choose a package when your project grows and you need to organize multiple modules logically. Packages help keep your codebase clean, avoid name clashes, and make it easier to maintain and distribute.

✅

Key Takeaways

A module is a single Python file; a package is a folder containing multiple modules.
Packages require an __init__.py file to be recognized by Python.
Use modules for small code groups and packages for larger, organized projects.
Import modules directly; import modules inside packages using dot notation.
Packages help avoid name conflicts and improve code organization in big projects.