Packages

Introduction

A single module is great for a handful of functions, but real applications quickly grow beyond one file. Python packages solve this by letting you group related modules together into folders, the same way you would organize files into folders on your computer.

In this lesson, you will learn what a package actually is, how to structure a small multi-file project as one, the difference between relative and absolute imports, and how the terms module, package, library, and framework relate to each other.

What is a Package?

A package is a directory that contains a collection of modules, along with a special file named __init__.py that tells Python to treat that directory as a package rather than just an ordinary folder.

Organizing a Project into a Package

Imagine you are building a small toolkit for a shop app, with separate modules for discounts and tax calculations, grouped inside a package named shop.

shop/
    __init__.py
    discounts.py
    tax.py
main.py

def apply_discount(price, percent):
    return price - (price * percent / 100)

def add_tax(price, rate=0.05):
    return price + (price * rate)

# Can be left empty, or used to expose specific names
from .discounts import apply_discount
from .tax import add_tax

from shop.discounts import apply_discount
from shop.tax import add_tax

price = 1000
price = apply_discount(price, 10)
price = add_tax(price)

print(f"Final price: {price}")

Final price: 945.0

The dotted path shop.discounts tells Python exactly where to look: inside the shop package, for the discounts module.

Absolute Imports

An absolute import spells out the full path to a module, starting from the top-level package or project root. This is what you saw above, and it is the most common and most readable style.

from shop.discounts import apply_discount
from shop.tax import add_tax

Relative Imports

A relative import refers to a module's location relative to the current module, using dots. A single dot (.) means "the current package," and two dots (..) mean "one level up."

shop/
    __init__.py
    discounts.py
    tax.py
    receipts.py

from .discounts import apply_discount
from .tax import add_tax

def build_receipt(price):
    price = apply_discount(price, 10)
    price = add_tax(price)
    return f"Total: {price}"

Here, .discounts means "the discounts module inside this same package." Relative imports only work inside packages, and only when the file is imported as part of that package — not when run directly as a standalone script.

Module vs Package vs Library vs Framework

These four terms are related but distinct, and it is easy to blur them together as a beginner.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

Packages give you a way to scale beyond single-file modules by grouping related code into directories that Python understands how to import. Absolute and relative imports each have their place, and knowing the difference avoids confusing import errors.

You also clarified the terminology that often confuses beginners: modules are files, packages are folders of modules, libraries are published reusable code, and frameworks provide the structure your code lives inside of.