Organize Python Code with Packages

When a Python project grows from a handful of modules to a few dozen, the flat directory structure that worked well in the beginning starts to show its limits. Modules with overlapping names accumulate, finding a specific function requires opening several files to remember where it lives, and the import statements at the top of each file grow into long lists that reference modules from across the entire project. This is the point where packages stop being an optional organizational tool and become necessary for keeping the codebase navigable and maintainable.

When you organize Python code with packages, the goal is not to follow a rigid template that applies to every project. It is about making intentional decisions about what belongs together, how deeply to nest the directory hierarchy, and how to design import paths so that a developer can find the code they need by thinking about the problem domain rather than memorizing file locations. This article covers the decision-making framework for structuring packages, the common project layout patterns, and the signs that tell you it is time to reorganize.

When to introduce packages into your project

The first sign that your project needs packages is that you have modules with names that would collide if they lived in the same directory. If you have a set of modules for handling user accounts and another set for processing payments, and both sets contain a module called validators, you need packages to create separate namespaces. The accounts package and the payments package each contain their own validators module, and imports use dotted names to disambiguate.

The second sign is conceptual distance. When you have modules that serve unrelated parts of the application, and a developer working on one part never needs to look at the other, those modules should live in separate packages. The package boundary communicates that the code inside is a self-contained subsystem with its own responsibilities, and it lets the team reason about the project as a composition of independent pieces rather than as a single undifferentiated mass of files.

The third sign is growth within a single module. When a module that started as a focused utility file grows past about five hundred lines, it is probably doing too many things and should be split into a package. The original module becomes the package's init file, which re-exports the public API, and the internal logic is distributed across focused submodules that each handle one aspect of the original module's responsibilities. This refactoring preserves the external import interface while improving internal navigability.

Common project layout patterns

The flat layout is the simplest structure and the right starting point for small projects. A single Python file sits at the project root alongside configuration files, and any additional modules live in the same directory. This layout works for scripts under a few hundred lines, for prototypes, and for projects that are not intended to be imported by other code. The flat layout is what most beginners use naturally, and it is the correct choice until you have a reason to introduce directories.

The package layout moves all source code into a named package directory with an init file. This is the standard structure for libraries and for applications that other developers will install. The package name becomes the top-level namespace, and all internal modules live inside it. Consumers import from the package name, and the internal directory structure is an implementation detail that the init file hides behind a curated public API. When you learned about creating and using Python packages, this was the structure you built. The same principles apply when importing built-in and custom modules: the package boundary keeps your custom code namespaced and prevents collisions with the standard library.

The following shows a clean package import where two subsystems each expose their functionality through a single top-level name:

python

from myapp.accounts import create_user
from myapp.payments import process_charge
 
user = create_user(email, password)
process_charge(user, amount)

The source layout adds an extra src directory between the project root and the package. The package lives at src/mypackage instead of just mypackage. This layout prevents a subtle but common problem: when the package directory is in the project root, running Python from the project root can import the package directly from the current directory instead of from the installed location, which masks import path errors that would appear when the package is installed elsewhere. The src layout catches these errors during development by forcing the package to be installed or the src directory to be explicitly added to the search path.

Deciding how deep to nest your packages

A package with a single level of nesting, meaning one directory with modules and an init file, is appropriate for most libraries and small applications. The flat internal structure is easy to navigate, and the init file provides a single point of control for the public API. You introduce subpackages only when the single-level package becomes too large to manage as a flat collection of modules.

A package with two levels of nesting, meaning subpackages within the main package, is common in medium to large applications. The top-level package represents the application or library, and the subpackages represent major subsystems like data access, business logic, API handlers, and user interface components. Each subpackage has its own init file that controls its internal API, and the top-level init file imports from the subpackages to present a unified interface.

Beyond two levels of nesting, you should question whether the hierarchy is genuinely serving the reader or just mirroring an organizational chart. A module path with four or five segments is hard to remember and harder to type, and it usually signals that the namespaces are too granular. Flatten the hierarchy by merging small packages that are always imported together, or by splitting a package that has grown too large into sibling packages at the same level rather than nesting them deeper.

A good test for whether your nesting depth is right is to look at a typical import statement in your project. If a developer has to write more than three dotted segments to reach a commonly used function, the hierarchy is probably too deep:

python

from myapp.services.payments.gateway import charge

This four-segment import suggests that gateway should live closer to the surface, perhaps directly under payments or even merged into a single payments module if the gateway logic is not large enough to justify its own subpackage.

Keeping package boundaries clean

The most important principle in package organization is that dependencies between packages should flow in one direction. If the accounts package imports from the payments package and the payments package imports from the accounts package, you have a circular dependency that makes both packages harder to understand, test, and refactor. The fix is to extract the shared code into a third package that both accounts and payments import without importing each other.

A related principle is that each package should have a single reason to change, just as each function should do one thing and each module should collect functions that serve one purpose. When a new feature requires changes to three different packages, it is a sign that the packages are too tightly coupled. When a feature can be implemented by changing code in a single package, the package boundaries are doing their job of isolating concerns.

The init file at each level of the package hierarchy is the gatekeeper that enforces clean boundaries. By controlling which names are exported from each package, you prevent internal implementation details from leaking into code that imports the package. A consumer who imports from the top-level package should not need to know which subpackage a function lives in, and a consumer who imports from a subpackage should not need to know which module inside that subpackage contains the implementation. For more on designing clean package interfaces, the article on the Python init.py file explains how to use the init mechanism to curate your package's public surface.