Python Modules & Packages Tutorial

The Story That Explains Modules & Packages

A module is a single Python file. A package is a folder of modules. The import statement is how one Python file borrows code from another. These three ideas turn Python from a scripting language into a language you can build entire systems in.

Script vs Module vs Package

Your First Module — A 90-Second Walkthrough

Let's build the smallest possible module. Two files, two seconds of work.

Step 1 — Create math_tools.py

# math_tools.py
PI = 3.14159

def area_circle(radius):
    return PI * radius ** 2

def area_square(side):
    return side ** 2

Step 2 — Create main.py in the same folder

# main.py
import math_tools

print(math_tools.area_circle(5))
print(math_tools.area_square(4))
print(math_tools.PI)

Step 3 — Run it

$ python main.py

That's it. You've created a module. The moment math_tools.py exists in the same directory as another Python file, the import statement can find it. No configuration, no build step.

The Six Import Styles — Know All of Them

# 1) Import the whole module — access via dotted path
import math
print(math.sqrt(16))          # 4.0

# 2) Import with an alias — great for long module names
import numpy as np
arr = np.array([1, 2, 3])

# 3) Import specific names — no dotted access needed
from math import sqrt, pi
print(sqrt(16))               # 4.0
print(pi)                     # 3.14159...

# 4) Import a name with an alias
from datetime import datetime as dt
now = dt.now()

# 5) Import everything — DANGEROUS, avoid in production
from math import *
print(sin(0))                # works, but where did sin come from?

# 6) Import a sub-module from a package
from os.path import join, exists
print(join("data", "file.csv"))

The if __name__ == "__main__" Idiom

Every Python file has a magic variable called __name__. When you run the file directly, __name__ equals "__main__". When you import it, __name__ equals the module's name. This one-line difference is what lets a file be both a script and a module.

# math_tools.py
def area_circle(radius):
    return 3.14159 * radius ** 2

def demo():
    print("Testing area_circle:")
    print(area_circle(5))
    print(area_circle(10))

# This block ONLY runs when you execute the file directly
if __name__ == "__main__":
    demo()

Packages — Modules Grow Up

When one file grows into ten, you group them into a folder — a package. Packages let you organise code by feature, share code across projects, and publish reusable libraries.

A package is any directory containing an __init__.py file. The __init__.py can be empty — its presence alone is what marks the folder as a package (in classic Python; modern Python 3 also supports "namespace packages" without it, but explicit is better).

Importing From a Package — Dotted Paths

Once you have a package structure, the import syntax uses dots to walk the folder tree — each dot descends one level.

# Given the mypackage/ structure above, from OUTSIDE the package:

# Import a top-level module
import mypackage.config
print(mypackage.config.DEBUG)

# Reach into a sub-package
import mypackage.core.engine
mypackage.core.engine.run()

# Cleaner — from ... import gives you a shorter name
from mypackage.core import engine
engine.run()

# Import a single function
from mypackage.core.engine import run
run()

# Alias for brevity
from mypackage.core import engine as eng
eng.run()

The __init__.py File — What Goes In It?

For most packages, __init__.py is empty. Its mere existence is enough. But it's also the perfect place to shape your package's public API.

Option 1 — Empty (Most Common)

# mypackage/__init__.py
# (empty)

# User must do the full path:
from mypackage.core.engine import run

Option 2 — Re-Export the Public API

# mypackage/__init__.py
from .core.engine import run, stop, restart
from .config import DEBUG, VERSION

# Now users can import directly from the package root:
from mypackage import run, stop, VERSION

# Instead of the deep path:
from mypackage.core.engine import run  # still works too

Option 3 — Define __all__ to Control * Imports

# mypackage/__init__.py
from .core.engine import run, stop, restart, _internal_helper

__all__ = ["run", "stop", "restart"]
# _internal_helper is intentionally EXCLUDED

# Now: from mypackage import * only pulls run/stop/restart
# _internal_helper is hidden from wildcard imports (still available directly)

Absolute vs Relative Imports

When code inside a package needs to import from another part of the same package, you have two choices: absolute (spell out the full path) or relative (use dots to navigate).

Dot Notation Cheat Sheet

# Inside mypackage/core/engine.py — three ways to import config.py

# 1) Absolute — clearest for outsiders reading the file
from mypackage import config

# 2) Relative with one dot — go to the same package (core/)
from . import utils           # imports core/utils.py

# 3) Relative with two dots — go up one level (mypackage/)
from .. import config         # imports mypackage/config.py

How Python Finds a Module — The Search Path

When you write import requests, Python has to find a file called requests. It searches a specific list of locations, in order, and uses the first match.

import sys
for path in sys.path:
    print(path)

Practical Example — Building a Small Package

Let's build a real, minimal package for text analysis. Four files, one working package that any other project could import.

Folder Structure

textstats/
    __init__.py
    counter.py
    reader.py
    _internal.py

textstats/_internal.py

# Internal helpers — leading underscore signals "private"
import re

def _clean(text):
    """Strip punctuation, lowercase, collapse whitespace."""
    text = re.sub(r"[^\w\s]", "", text.lower())
    return " ".join(text.split())

textstats/counter.py

from ._internal import _clean       # relative import — same package
from collections import Counter

def word_count(text):
    """Total words in a piece of text."""
    return len(_clean(text).split())

def top_words(text, n=5):
    """Return the n most common words as (word, count) tuples."""
    return Counter(_clean(text).split()).most_common(n)

textstats/reader.py

from pathlib import Path

def read_file(path):
    """Load the full text of a file."""
    return Path(path).read_text(encoding="utf-8")

textstats/__init__.py — The Public API

# Expose the useful names at the package top level
from .counter import word_count, top_words
from .reader import read_file

__version__ = "1.0.0"
__all__ = ["word_count", "top_words", "read_file"]

Using the Package From Anywhere

# In some other script:
import textstats

text = textstats.read_file("speech.txt")
print(textstats.word_count(text))
print(textstats.top_words(text, n=3))

# Or the short form thanks to __init__.py re-exports:
from textstats import word_count, top_words

The Standard Library — Modules You Already Have

Python ships with hundreds of modules. Knowing even a handful saves you from reinventing basics and from installing third-party packages you don't need.

Third-Party Packages — pip, requirements, and venv

Beyond the standard library, hundreds of thousands of packages live on PyPI (the Python Package Index). Installing them is a one-liner.

# Install a package
$ pip install requests

# Install a specific version
$ pip install "pandas==2.1.0"

# Install from a requirements file (reproducible builds)
$ pip install -r requirements.txt

# Freeze current environment to a requirements file
$ pip freeze > requirements.txt

# List what's installed
$ pip list

# Uninstall
$ pip uninstall requests

Virtual Environments — Non-Negotiable For Real Projects

# Create an isolated Python environment for THIS project only
$ python -m venv .venv

# Activate it (macOS/Linux)
$ source .venv/bin/activate

# Activate it (Windows)
$ .venv\Scripts\activate

# Now pip install goes ONLY into this project
(.venv) $ pip install requests pandas

# Leave the environment
(.venv) $ deactivate

Common Pitfalls

Circular Import Example — Broken vs Fixed

# ── BROKEN ──
# users.py
from orders import Order
class User: ...

# orders.py
from users import User        # ← circular!
class Order: ...

# ── FIXED — defer the import into the function ──
# orders.py
class Order:
    def notify_user(self):
        from users import User    # imported only when called
        ...

# ── BETTER — extract shared types to a third module ──
# models.py has both User and Order
# users.py and orders.py both import from models

Golden Rules