Python Project Structure: How to Choose the Right Layout

Your Python project structure, also known as your project layout, is the arrangement of files and directories that determines how your code gets imported, tested, and packaged. Choosing between a flat and a src/ layout depends on the type of project you’re building and the trade-offs you accept.

In this tutorial, you’ll turn those choices into confident defaults for libraries and for CLI, web, and GUI applications.

By the end of this tutorial, you’ll understand that:

• The type of project you build, whether a script, an application, or a library, points to the layout that fits.
• A flat layout keeps the importable package at the project root, so you can import it without installing anything.
• A src/ layout hides the package behind an install step, so your tests exercise the same code your users receive.
• A thin __main__.py paired with a [project.scripts] table in pyproject.toml is the modern way to define the project’s entry point, and it replaces older approaches like setup.py or a bin/ directory.
• Domain-named subpackages like core/ and api/ scale better than catch-all modules like utils.py.

To follow along, it helps if you’re comfortable with Python modules and packages and if you’ve run a script or two from the command line.

You won’t install anything or build a full application here. Instead, several annotated directory trees will show you why each file belongs where it does.

Understanding Why Python Project Structure Matters

A directory layout can feel like bookkeeping, but it shapes every interaction that you and your teammates have with the code. The payoff of a clear layout shows up in several concrete ways, including the following:

• Lower cognitive load: When every file sits in a descriptively named directory and has a name that signals what it holds, a contributor who opens the repository for the first time can guess where things live instead of grepping around.
• Predictable imports: When your directories mirror the way you import them, you can read a module’s dotted import name straight off the directory tree rather than hunting for where it lives.
• Reliable tests: When your tests find the package and modules just as your users will, running pytest behaves the same in continuous integration (CI) as it does on your computer.
• Smooth packaging: When you ship a library to PyPI, build a CLI binary, deploy a web service in a container, or freeze a desktop app with PyInstaller, the right layout means the wheel, installer, or image holds exactly what you expect. You end up with no missing assets, no stowaway test files, and no broken entry points.

All of these benefits rest on a vocabulary distinction worth getting straight early. The project is the whole repository, including its configuration, tests, and documentation. The package is the importable code that lives inside the project. Keeping the two ideas separate makes the rest of this tutorial click into place because most layout questions come down to where the package sits relative to everything else.

If you want a refresher on the import machinery behind these ideas, then the project layout reference makes a good companion. With the vocabulary in hand, you can start narrowing your options by naming the type of project that you’re building.

Identifying the Type of Project You’re Building

Before you start learning about layouts, you need to know what you’re laying out. Python projects fall into three broad types, and each one has its own typical layout:

• Scripts: One or a few .py files that you run directly. They need no installation and often no pyproject.toml, or at most a PEP 723 inline header. A data-cleanup script or a cron job fits here.
• Applications: Software that you run or deploy, rather than code that others import. This is where Python application structure varies the most, covering CLIs, web apps, GUI apps, and background workers. Web apps use frameworks like Django, Flask, or FastAPI, while GUI apps rely on tools like PyQt, Tkinter, Toga, or Kivy. You ship them as a container, a wheel, or an installer.
• Libraries: Importable code that other projects depend on. You can distribute a library through PyPI, and your users consume it with import package_name. Familiar examples include requests, HTTPX, and Rich.

A couple of cases sit at the edges of this taxonomy and could cause confusion:

• A plugin, like pytest-cov, is a specialized library that gets consumed through a [project.entry-points] table in pyproject.toml instead of a direct import.
• A hybrid, like pytest, mypy, or black, ships as both a library and a command-line tool. The structural rule is to build the project around the more demanding half, usually the library, and then add the CLI as a thin cli.py with a [project.scripts] entry.

Naming the project type is the first step of the layout decision because the type alone points you to a default you can adopt unless you have a reason not to:

This table shows where you’ll end up. Here’s a short, repeatable workflow that you’ll follow throughout the rest of this tutorial:

1. Identify the type of Python project.
2. Pick a layout.
3. Organize the package from the inside out.

Those three steps will guide your decision-making, starting with the type of project you’re building and the layout it points to:

With the project type settled, take a closer look at the two main layouts that cover nearly every Python project.