Python Tutorial — Learn Python Step by Step

Python Package

A package is a directory containing Python modules and a special __init__.py file. Packages let you organize related modules into a hierarchical structure.

Package Structure

# A typical package structure:
# myproject/
# ├── __init__.py          # makes this directory a package
# ├── core.py              # module with core logic
# ├── utils.py             # utility functions
# └── models/              # sub-package
#     ├── __init__.py
#     ├── user.py
#     └── product.py

# __init__.py can be empty or contain package initialization code

Creating a Package

# File: mypackage/__init__.py
"""My reusable package."""
__version__ = "1.0.0"

# Optionally expose key items at package level
from .core import process_data
from .utils import clean_text

# File: mypackage/core.py
def process_data(data):
    """Process raw data and return results."""
    return [item.strip().lower() for item in data]

# File: mypackage/utils.py
def clean_text(text):
    """Remove extra whitespace."""
    return " ".join(text.split())

def format_name(first, last):
    """Format a full name."""
    return f"{first.title()} {last.title()}"

Importing from Packages

# Import the package (runs __init__.py)
import mypackage
print(mypackage.__version__)  # "1.0.0"

# Import a module from the package
from mypackage import utils
print(utils.clean_text("  hello   world  "))

# Import a specific function
from mypackage.utils import format_name
print(format_name("john", "doe"))  # "John Doe"

# Import from sub-package
from mypackage.models.user import User

# Alias for convenience
from mypackage.core import process_data as process

Relative Imports (Within a Package)

# File: mypackage/core.py
# Use relative imports to reference other modules in the same package

from .utils import clean_text          # same directory
from .models.user import User          # sub-package
from ..shared import constants         # parent package (if nested)

# Relative import syntax:
# .  = current package
# .. = parent package
# ... = grandparent package

# Note: relative imports only work inside packages
# Running a file directly (python core.py) breaks relative imports
# Always run from outside: python -m mypackage.core

Package with __init__.py Configuration

# File: mypackage/__init__.py

# Control what "from mypackage import *" exports
__all__ = ["process_data", "clean_text", "User"]

# Package-level imports for convenient access
from .core import process_data
from .utils import clean_text
from .models.user import User

# Now users can do:
# from mypackage import process_data, User
# instead of:
# from mypackage.core import process_data
# from mypackage.models.user import User

Installing Your Own Package

# Create a minimal pyproject.toml (modern standard)
# mypackage/
# ├── pyproject.toml
# ├── src/
# │   └── mypackage/
# │       ├── __init__.py
# │       └── core.py

# pyproject.toml content:
# [project]
# name = "mypackage"
# version = "1.0.0"
# [build-system]
# requires = ["setuptools"]
# build-backend = "setuptools.backends._legacy:_Backend"

# Install in development mode:
# pip install -e .
# Now you can import mypackage from anywhere

• A package is a directory with __init__.py — it groups related modules together.
• Use __init__.py to expose a clean public API and control import * behavior.
• Use relative imports (from .module import func) within packages.
• Run package modules with python -m package.module to avoid import issues.
• Use pip install -e . for development to make your package importable globally.