Python Modules and Packages: Organize Your Code Like a Pro

What Is a Module?

A module is simply a Python file. When your project grows beyond a single file, you start splitting code into modules so each file has one clear purpose.

Python ships with a huge standard library of built-in modules. You’ve probably used them already:

import math
import os
import datetime

print(math.sqrt(16))       # 4.0
print(os.getcwd())         # Current directory
print(datetime.date.today())  # Today's date

Import Styles

There are three main ways to import, each with a different trade-off:

# 1. Import the whole module (safest, most readable)
import math
print(math.pi)

# 2. Import specific names (convenient for frequently used items)
from math import pi, sqrt
print(pi)
print(sqrt(9))

# 3. Import with an alias (useful for long module names)
import datetime as dt
print(dt.date.today())

Avoid from module import * — it clutters your namespace and makes it hard to know where names come from.

Creating Your Own Module

Any Python file is a module. Create a file called utils.py:

# utils.py
def greet(name):
    return f"Hello, {name}!"

def add(a, b):
    return a + b

PI = 3.14159

Then import it from another file in the same directory:

# main.py
import utils

print(utils.greet("Alice"))   # Hello, Alice!
print(utils.add(3, 4))        # 7
print(utils.PI)               # 3.14159

What Is a Package?

A package is a folder of modules with a special file called __init__.py. This file (which can be empty) tells Python to treat the folder as a package.

my_project/
├── main.py
└── tools/
    ├── __init__.py   ← makes tools/ a package
    ├── math_utils.py
    └── string_utils.py

# main.py
from tools import math_utils
from tools.string_utils import capitalize

print(math_utils.add(2, 3))
print(capitalize("hello"))

Installing Third-Party Packages with pip

pip is Python’s package manager. It installs packages from PyPI, the Python Package Index (over 450,000 packages available).

# Install a package
pip install requests

# Install a specific version
pip install requests==2.31.0

# See what's installed
pip list

# Save your project's dependencies
pip freeze > requirements.txt

# Reinstall from requirements.txt (great for sharing projects)
pip install -r requirements.txt

The if __name__ == “__main__” Pattern

When Python runs a file directly, __name__ equals "__main__". When it’s imported as a module, __name__ equals the module name. This pattern lets you write code that works both as a script and as an importable module:

# utils.py
def add(a, b):
    return a + b

if __name__ == "__main__":
    # This only runs when you run utils.py directly
    # NOT when you import it from another file
    print(add(5, 3))

Modules and packages are the foundation of clean Python projects. Start by splitting your code into logical modules, group them into packages as your project grows, and use pip to pull in the thousands of battle-tested packages the community has built.