Python Modules & Packages: Structure Your Projects

As your programs grow beyond a single file, you need a way to split code into manageable, reusable pieces. Python’s module and package system lets you do exactly that: put related functions and classes in their own .py file, then import exactly what you need wherever you need it. This page takes you from importing a single function all the way to structuring a multi-file project.

What is a Module?

A module is any Python file with a .py extension. Every variable, function, and class defined in that file becomes part of the module’s namespace and can be imported by other files. Suppose you create calculator.py:

# calculator.py

PI = 3.14159

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

def subtract(a, b):
    return a - b

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

You can now use it from main.py in the same directory:

# main.py

import calculator

print(calculator.add(5, 3))          # 8
print(calculator.circle_area(7))     # 153.93797...
print(calculator.PI)                 # 3.14159

Import Styles

import module
from module import name
import module as alias
from module import *

Imports the entire module. Access members using module.name:

import math

print(math.sqrt(16))   # 4.0
print(math.pi)         # 3.141592653589793

Best when you use many things from the module and want to keep the namespace clear.

Imports specific names directly into your namespace:

from math import sqrt, pi

print(sqrt(25))   # 5.0
print(pi)         # 3.141592653589793

Best when you use only one or two items and want cleaner call sites.

Imports the module under a shorter alias:

import datetime as dt

now = dt.datetime.now()
print(now.strftime("%Y-%m-%d"))

Best when the module name is long or clashes with a local name.

Imports everything into the local namespace. Avoid this in production code — it pollutes the namespace and makes it impossible to tell where a name came from.

from math import *   # avoid — hard to trace where 'sqrt' came from

The `if name == 'main'` Pattern

When Python runs a file directly, it sets the special variable __name__ to "__main__". When the file is imported by another module, __name__ is set to the module’s own name instead. This lets you guard code that should only run when the file is executed directly:

# calculator.py

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

def subtract(a, b):
    return a - b

if __name__ == "__main__":
    # This block runs only when you execute: python calculator.py
    # It does NOT run when someone does: import calculator
    print("Running calculator tests...")
    print(add(10, 5))       # 15
    print(subtract(10, 5))  # 5

Always use this pattern to separate reusable library code from executable scripts. It makes your modules safe to import without triggering side effects.

Built-in Standard Library Modules

Python ships with a comprehensive standard library — no installation needed.

`math` — Mathematics

import math

print(math.sqrt(144))      # 12.0
print(math.floor(3.7))     # 3
print(math.ceil(3.2))      # 4
print(math.pi)             # 3.141592653589793
print(math.log(100, 10))   # 2.0

`random` — Random Numbers

import random

print(random.randint(1, 10))              # random int between 1 and 10
print(random.choice(["heads", "tails"]))  # random element from a list
print(random.random())                    # float in [0.0, 1.0)

deck = list(range(1, 14))
random.shuffle(deck)
print(deck[:5])                           # first 5 after shuffle

`datetime` — Dates and Times

import datetime

# Current date and time
now = datetime.datetime.now()
print(now)                                      # 2025-07-20 14:30:00.123456

# Formatting
print(now.strftime("%Y-%m-%d %H:%M"))           # 2025-07-20 14:30

# Parsing
deadline = datetime.datetime.strptime("2025-12-31", "%Y-%m-%d")
days_left = (deadline - now).days
print(f"Days until deadline: {days_left}")

# Arithmetic
tomorrow = now + datetime.timedelta(days=1)
print(tomorrow.date())

`os` — Operating System Interface

import os

print(os.getcwd())                         # current working directory
print(os.listdir("."))                     # files in current directory
os.makedirs("output/logs", exist_ok=True)  # create nested directories

# Environment variables
debug = os.environ.get("DEBUG", "false")
db_url = os.environ.get("DATABASE_URL", "sqlite:///local.db")
print(f"Database: {db_url}")

`sys` — System Information

import sys

print(sys.version)        # Python version string
print(sys.platform)       # 'linux', 'darwin', or 'win32'

# Command-line arguments
# When you run: python myscript.py hello world
print(sys.argv)           # ['myscript.py', 'hello', 'world']

# Exit the program
# sys.exit(0)   # 0 = success, non-zero = error

Creating Your Own Module

Write your functions in a .py file

Create utils.py in your project directory:

# utils.py

def celsius_to_fahrenheit(c):
    """Convert Celsius to Fahrenheit."""
    return c * 9 / 5 + 32

def clamp(value, minimum, maximum):
    """Clamp a value to the given range."""
    return max(minimum, min(value, maximum))

def chunk(lst, size):
    """Split a list into chunks of the given size."""
    return [lst[i:i + size] for i in range(0, len(lst), size)]

Import and use it in another file

In main.py (same directory):

# main.py

from utils import celsius_to_fahrenheit, chunk

print(celsius_to_fahrenheit(100))     # 212.0
print(celsius_to_fahrenheit(0))       # 32.0

data = list(range(10))
print(chunk(data, 3))
# [[0, 1, 2], [3, 4, 5], [6, 7, 8], [9]]

What is a Package?

A package is a directory that contains one or more module files plus a special file named __init__.py. The presence of __init__.py tells Python to treat the folder as an importable package.

Simple Package Structure

my_project/
├── main.py
└── mypackage/
    ├── __init__.py
    ├── math_utils.py
    └── text_utils.py

math_utils.py:

# mypackage/math_utils.py

def square(x):
    return x ** 2

def cube(x):
    return x ** 3

text_utils.py:

# mypackage/text_utils.py

def title_case(text):
    return text.title()

def word_count(text):
    return len(text.split())

__init__.py — expose the most-used names at the package level:

# mypackage/__init__.py

from .math_utils import square, cube
from .text_utils import title_case, word_count

main.py:

# main.py

# Import from the package root (thanks to __init__.py)
from mypackage import square, title_case

print(square(5))              # 25
print(title_case("hello ai")) # Hello Ai

# Or import the sub-module directly
from mypackage import math_utils
print(math_utils.cube(3))     # 27

Realistic Multi-File Project Layout

As your project grows, a typical structure looks like this:

my_app/
├── main.py                 # entry point
├── config.py               # settings & environment variables
├── models/
│   ├── __init__.py
│   ├── user.py
│   └── product.py
├── services/
│   ├── __init__.py
│   ├── auth.py
│   └── pricing.py
└── utils/
    ├── __init__.py
    └── helpers.py

Keep each module focused on a single responsibility. A module named user.py should only contain user-related code. This makes the project easy to navigate and test.

Key Takeaways

Module = .py file

Any .py file is a module. Break your code into files the moment a single file grows hard to navigate.

Standard library first

Before installing a third-party package, check whether math, datetime, os, random, or another built-in module already solves your problem.

init.py controls the API

Use __init__.py to decide which names are public. Import the most-used names there so consumers don’t need to know the internal file structure.

if name == 'main'

Guard executable code with this pattern to keep modules both importable as a library and runnable as a script.

Core Python

Advanced Python

Pydantic

Python Modules & Packages: Structure Your Projects

What is a Module?

Import Styles

The `if name == 'main'` Pattern

Built-in Standard Library Modules

`math` — Mathematics

`random` — Random Numbers

`datetime` — Dates and Times

`os` — Operating System Interface

`sys` — System Information

Creating Your Own Module

What is a Package?

Simple Package Structure

Realistic Multi-File Project Layout

Key Takeaways

Module = .py file

Standard library first

init.py controls the API

if name == 'main'

​What is a Module?

​Import Styles

​The if __name__ == '__main__' Pattern

​Built-in Standard Library Modules

​math — Mathematics

​random — Random Numbers

​datetime — Dates and Times

​os — Operating System Interface

​sys — System Information

​Creating Your Own Module

​What is a Package?

​Simple Package Structure

​Realistic Multi-File Project Layout

​Key Takeaways

Module = .py file

Standard library first

__init__.py controls the API

if __name__ == '__main__'

What is a Module?

Import Styles

The `if name == 'main'` Pattern

Built-in Standard Library Modules

`math` — Mathematics

`random` — Random Numbers

`datetime` — Dates and Times

`os` — Operating System Interface

`sys` — System Information

Creating Your Own Module

What is a Package?

Simple Package Structure

Realistic Multi-File Project Layout

Key Takeaways

init.py controls the API

if name == 'main'