A Python package is a folder of modules with an __init__.py file inside it, and the layout that you choose decides how other people import your code. That includes you in six months, when you have forgotten everything. This guide builds one small package from scratch and shows exactly which file each import statement needs, so that you stop guessing why from shop.cart import add_item fails.
The previous lesson in this module covered "Imports, Modules and the import Path System", and the next lesson in this module is about "pip, venv and Managing Dependencies".
What does __init__.py actually do?
Historically, __init__.py was mandatory and it was usually empty. Since Python 3.3, a folder without one can still be imported as a namespace package, but that is an edge case. Tools, build systems, and editors all assume the regular layout, so create __init__.py every single time.
Three things make it worth the effort. First, the file runs whenever the package is imported, which makes it the right place for setup that the whole package needs. Second, it gives the package a public face. You re-export the names that other modules should use, and you hide the rest. Third, __all__ inside it defines exactly what from shop import * exposes to the outside world.
That public face is what makes import shop pleasant to use. Without the re-exports in __init__.py, a caller would have to know that cart_total lives in cart.py and write from shop.cart import cart_total. With them, the package tells its own users what it offers them.
The discipline that keeps packages healthy is to keep __init__.py light. Every name that you import there is executed on every single import of the package, even on imports that only needed one small helper. Heavy work in __init__.py slows down the start of your program and makes circular imports much easier to create by accident.
What does a well-structured package look like?
Here is a complete and runnable package with four files, and each file has one job. The first holds the catalogue of prices and the tax rules. The second holds the basket operations. The third is the public API of the package. The fourth is the entry point that you can run.
shop/
├── __init__.py # the public API of the package
├── __main__.py # runs when you type: python -m shop
├── cart.py # basket operations
└── pricing.py # catalogue, tax rate and discounts
# shop/pricing.py
"""Price rules: the catalogue, the tax rate and the discount table."""
TAX_RATE = 0.2
CATALOGUE = {
'mug': 9.99,
'tote': 14.50,
'pencil': 1.25,
}
DISCOUNTS = {'SAVE10': 0.10, 'SAVE20': 0.20}
def unit_price(item):
"""Return the unit price of an item."""
return CATALOGUE[item]
def apply_discount(amount, code=None):
"""Return the amount with any discount applied, plus tax."""
rate = DISCOUNTS.get(code or '', 0.0)
return (amount * (1 - rate)) * (1 + TAX_RATE)
if __name__ == '__main__':
print('mug price:', unit_price('mug'))
print('20.00 with SAVE10:', round(apply_discount(20.00, 'SAVE10'), 2))
# shop/cart.py
"""Basket operations built on the pricing rules."""
from .pricing import apply_discount, unit_price
def add_item(basket, item, qty=1):
"""Add qty of an item to the basket and return the same basket."""
if qty <= 0:
raise ValueError('quantity must be positive')
basket[item] = basket.get(item, 0) + qty
return basket
def subtotal(basket):
"""Return the total before tax and before any discount."""
total = 0.0
for item, qty in basket.items():
total += unit_price(item) * qty
return total
def cart_total(basket, code=None):
"""Return the final total including the discount and the tax."""
return apply_discount(subtotal(basket), code)
if __name__ == '__main__':
demo = {}
add_item(demo, 'tote')
print('subtotal:', round(subtotal(demo), 2))
# shop/__init__.py
"""A tiny shopping-basket package used to show package layout."""
from .cart import add_item, cart_total, subtotal
from .pricing import CATALOGUE, TAX_RATE, apply_discount
__all__ = [
'add_item',
'cart_total',
'subtotal',
'apply_discount',
'CATALOGUE',
'TAX_RATE',
]
__version__ = '1.0.0'
# shop/__main__.py
"""Run the package demo with: python -m shop"""
from .cart import add_item, cart_total
def main():
basket = {}
add_item(basket, 'mug', 2)
add_item(basket, 'pencil')
print('basket:', basket)
print('total:', round(cart_total(basket), 2))
print('total with SAVE10:', round(cart_total(basket, 'SAVE10'), 2))
if __name__ == '__main__':
main()
Every module carries its own if __name__ == '__main__': demo, so you can run any one of them directly with python -m shop.cart while you are working on it. That habit of keeping every module runnable is what stops a package from becoming impossible to debug as it grows.
Should you use relative or absolute imports?
Inside a package, the leading dot means "relative to the package that I live in". One dot is the current package, and two dots is the parent package. The cart.py listing above uses from .pricing import apply_discount, unit_price, which means "the pricing module that sits next to me". The same module can also be named from the outside with from shop.pricing import unit_price.
import shop
from shop import add_item, cart_total
from shop.pricing import unit_price
print('version:', shop.__version__)
print('public names:', len(shop.__all__))
print('mug price:', unit_price('mug'))
basket = {}
add_item(basket, 'mug', 2)
print('total:', round(cart_total(basket), 2))
| Style | Example | Use it when |
|---|---|---|
| Relative | from .pricing import unit_price | You are writing code inside a package and the package may be renamed or copied into another project. |
| Absolute | from shop.pricing import unit_price | You are writing a script, a test, or code that lives outside the package. |
| Implicit relative | from pricing import unit_price | Never in Python 3. It raises ModuleNotFoundError, and it used to work in Python 2. |
Mixing the two styles inside one file is the smell to watch for. Use relative imports inside packages and absolute imports in tests and scripts, and the whole codebase stays predictable when you move or rename a package.
How do you actually run a package?
There are two supported entry points, and they behave differently from each other.
# Run the package's __main__.py from the folder that contains it.
python -m shop
# Run one module of the package.
python -m shop.cart
# What does NOT work from outside the package folder.
python shop/__main__.py
The -m flag is not just a shortcut. When you run python -m shop, Python puts your current working directory on sys.path and imports shop as a package, so the relative imports inside it resolve correctly. When you run python shop/__main__.py, Python treats that file as a top-level script, the package context is gone, and from .cart import add_item fails with ImportError: attempted relative import with no known parent package.
The same mechanism powers the console_scripts entry points that the packaging tools generate for you. When you install your package, the console script calls shop.__main__:main on your behalf, and that is exactly why writing a __main__.py is worth the effort.
One wrinkle is worth knowing about, because it looks alarming the first time that you meet it. Since shop/__init__.py imports cart eagerly, running python -m shop.cart makes Python 3.13 print RuntimeWarning: 'shop.cart' found in sys.modules after import of package 'shop'. Nothing is actually broken. The module was simply imported once as part of the package and once as the program that you asked for. It is a good argument for keeping the real entry point in __main__.py and treating the per-module runs as a debugging convenience.
Which folder layout should you pick?
| Layout | Shape | Verdict |
|---|---|---|
| Flat | myapp/ and tests/ sit next to pyproject.toml at the root | Perfect for a small project or a learning exercise. It is the simplest thing that works. |
| Src | src/myapp/ holds the code, and the tests live outside it | The best default for anything that you intend to publish. The tests import the installed package and not the folder, so a broken layout fails loudly instead of quietly. |
| Namespace | No __init__.py anywhere | For splitting one package across several distributions. It is rare, it is advanced, and it is worth avoiding until you really need it. |
Whatever layout you choose, the import statements stay identical. That is the whole point of it. The layout is a deployment decision, and the import path is a public contract that other code depends on.
With the src layout, the code lives in src/myapp/ and nothing sits loose at the root. That forces you to install the package before your tests can import it, which sounds like friction but is really the point, because it proves that the package is importable from outside its own folder, exactly as a user would experience it. A flat layout lets import myapp succeed just because you happened to run pytest from the right folder, and that success disappears the moment somebody runs it from somewhere else.
Quick reference
__init__.pymarks a folder as a regular package, and it runs on every import of that package.- Re-export deliberately with explicit imports plus
__all__, and keep the file free of heavy work. - Use
from .module import nameinside a package, and absolute imports in scripts and tests. - Give the package a
__main__.pyso thatpython -m packageworks and console scripts have a target. - Choose the src layout for anything that you plan to publish, and the flat layout is fine for learning.
Try it yourself: Build the four-file shop package from this page inside a folder called shop-lab. Run python -m shop from inside shop-lab and note the three lines of output. Then run python shop/__main__.py from the same folder and read the error, because it shows exactly why -m exists. Finally, add a fifth module shop/loyalty.py with a points_for(total) function, import it from shop/__init__.py, and confirm that python -m shop still works.