src Layout & Package Structure

The src/ layout installs your package before tests run, so imports match production and accidental "works on my laptop" path hacks fail in CI.

Recipe

Quick-reference recipe card - copy-paste ready.

# pyproject.toml (excerpt)
[project]
name = "billing"
version = "0.1.0"
requires-python = ">=3.14"
 
[tool.setuptools.packages.find]
where = ["src"]
 
# src/billing/__init__.py
"""Billing domain package."""
 
# tests/test_invoice.py
from billing.invoices import compute_total
 
def test_compute_total() -> None:
    assert compute_total([10, 20]) == 30

When to reach for this:

• Any installable library or service packaged for Docker/CI
• Teams hitting import errors only in CI or after pip install
• Projects splitting domain, adapters, and CLI entry points
• Monorepos with multiple packages under one repo

Working Example

# pyproject.toml
[build-system]
requires = ["setuptools>=75"]
build-backend = "setuptools.build_meta"
 
[project]
name = "orders"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = ["pydantic>=2"]
 
[project.scripts]
orders-api = "orders.cli:main"
 
[tool.setuptools.packages.find]
where = ["src"]
 
# src/orders/__init__.py
__all__ = ["domain", "adapters"]
 
# src/orders/domain/models.py
from dataclasses import dataclass
 
@dataclass(frozen=True)
class LineItem:
    sku: str
    quantity: int
    unit_price_cents: int
 
# src/orders/domain/totals.py
from orders.domain.models import LineItem
 
def order_total(items: list[LineItem]) -> int:
    return sum(i.quantity * i.unit_price_cents for i in items)
 
# src/orders/adapters/memory_repo.py
from orders.domain.models import LineItem
 
class InMemoryOrderRepo:
    def __init__(self) -> None:
        self._items: list[LineItem] = []
 
    def add(self, item: LineItem) -> None:
        self._items.append(item)
 
    def list_items(self) -> list[LineItem]:
        return list(self._items)
 
# src/orders/cli.py
from orders.adapters.memory_repo import InMemoryOrderRepo
from orders.domain.models import LineItem
from orders.domain.totals import order_total
 
def main() -> None:
    repo = InMemoryOrderRepo()
    repo.add(LineItem("ABC", 2, 1500))
    print(order_total(repo.list_items()))
 
if __name__ == "__main__":
    main()

What this demonstrates:

• Package code lives under src/orders/, tests import orders as an installed name
• Domain (models, totals) stays free of CLI and persistence details
• project.scripts exposes a stable console entry point
• requires-python documents the 3.14 floor from day one

Deep Dive

How It Works

• pip install -e . (or uv sync) puts src/orders on sys.path as top-level orders
• Tests and apps import orders.domain, not src.orders.domain
• Editable installs re-read source changes without reinstalling
• CI that only sets PYTHONPATH=. hides missing packaging metadata

Recommended Tree

my-service/
  pyproject.toml
  src/
    my_service/
      __init__.py
      domain/
      adapters/
      api/          # FastAPI/Flask routers
  tests/
    test_domain.py
  README.md

Packaging Commands

Python Notes

# Avoid package/module name collisions
# BAD: src/orders.py AND src/orders/ package
# GOOD: one package directory with submodules
 
# Explicit public API in __init__.py
from orders.domain.totals import order_total as order_total
__all__ = ["order_total"]

Gotchas

• Testing without install - pytest passes locally because the repo root is on sys.path, then fails in Docker. Fix: always pip install -e . in CI before tests.
• Duplicate package names - a orders.py file next to orders/ shadows the package. Fix: one layout convention; delete stray top-level modules.
• Implicit relative imports in scripts - from models import X breaks when run as a module. Fix: absolute imports from the package root (from orders.domain.models import X).
• Missing __init__.py - namespace packages can work but confuse tooling and explicit exports. Fix: add __init__.py unless you deliberately need PEP 420 namespaces.
• Deep nesting without purpose - src/foo/bar/baz/qux with one function per file. Fix: flatten until a folder has a clear boundary (domain, api, adapters).
• Tests inside src/ - shipped accidentally in wheels. Fix: keep tests in top-level tests/.

Alternatives

FAQs

Related

• Project Architecture Decision Checklist - layout decision in context
• Clean / Hexagonal Architecture - domain vs adapters folders
• Dependency Injection & Wiring - wiring modules at the composition root
• Configuration & Settings - settings module placement
• Circular Import Scenarios - cycles from bad package graphs

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Y29kZWd1aWRlcy5pb3xjZ2lvNjI0fDIwMjYwNw==