Python Project Structure: How to Choose the Right Layout

Using the Flat Layout

A flat layout keeps the package at the root, so you can run your code without installing anything, and a script in the repository can import project_name directly. Most applications use this layout.

For example, the following all sit flat: every project generated by Django’s startproject, the official Flask flaskr/ tutorial package, and FastAPI’s bigger-applications structure.

The convenience comes with one catch. Because the current directory is already on Python’s import path, a flat layout can mask packaging mistakes.

A module that imports fine on your machine might be missing from the wheel entirely, and you wouldn’t notice until a user did. The fix is to run your tests against an installed copy in CI, so the test environment resembles a real install instead of your working directory.

Using the src/ Layout

A src/ layout removes the import issue that a flat layout creates. None of your package’s code becomes importable until you run python -m pip install -e . or a similar editable install, so your tests run against the same installed package that your users will get.

You can watch this difference play out below. Switch between the two layouts and run the steps to see how the same import behaves in each:

Because only the contents of src/ become importable once you install your project, stray Python code at the root, like a tools/ helper or an examples/ directory, can’t sneak onto the import path and shadow your real package.

The official packaging guide spells out these benefits in its discussion of the src/ layout versus the flat layout. There’s a bonus for distribution, too. Since the importable package sits in its own directory, the wheel mirrors src/ one-to-one, so what you see in the tree is what ships.

The trade-off is the editable install itself. Root-level scripts can’t import the package until you install it, and every contributor has to remember that first python -m pip install -e . step.

Choosing Between Flat and src/

The benefits of src/ apply to applications, not just libraries, and the decision is a judgment call rather than a rule. In most cases, you can match your situation to the right layout:

As a rule of thumb, a flat layout is a fine starting point until you have a specific reason to switch. Many mature projects never find that reason. When the time does come, migrating is mechanical: you move the package into the src/ directory and point the build backend at it. With setuptools, that’s a single configuration line:

[tool.setuptools.packages.find]
where = ["src"]

Once you’ve settled on where the package sits, the next concern is how to organize the code inside it.

Adding Modules

Modules are the .py files that live inside a package directory. The __init__.py files are also modules, but they play a special role: Their presence marks the containing directory as a regular package that Python can import.

An __init__.py can re-export the names that callers are meant to import, set __all__, and sometimes expose a __version__ constant. For example, the package_name/__init__.py below re-exports two names and sets a version constant:

from package_name.core import load_config, run

__version__ = "1.0.0"
__all__ = ["load_config", "run"]

In this example, the __init__.py keeps the public API small and intentional, so callers import load_config from the top of the package without reaching into the module where it happens to be defined.

A few best practices will keep this file healthy:

• Avoid doing expensive work at import time.
• Steer clear of side effects like network calls or file writes.
• Watch for circular imports, since the main package’s __init__.py runs whenever anyone imports the package.

All three guidelines keep the main package’s __init__.py lightweight, so importing the package stays fast and free of surprises. With your modules in order, the next layer turns the package into something you can run.

Adding Entry Points

When you want to run your project from the command line, you need an entry-point script. In a modern project, that script is a __main__.py file rather than a bin/ directory or another legacy approach. Keeping __main__.py thin is also a best practice. Typically, it imports a main() function from a module like cli.py or app.py and calls it. The example below uses cli.py:

from package_name.cli import main

main()

As the Python documentation for __main__ explains, this file runs whenever someone executes python -m package_name. The docs recommend leaving out the if __name__ == "__main__" idiom here, since __main__.py files stay short and skipping the guard keeps the behavior consistent across regular packages and zip archives.

To turn that entry point into a real command, you add a [project.scripts] table to pyproject.toml:

[project.scripts]
package_name = "package_name.cli:main"

On install, that line generates a package_name executable on the user’s PATH, wired straight to your main() function. Your users get a standalone command without ever typing python -m.

Grouping in Subpackages

As modules multiply, you’ll feel the pull to dump loose functions into catch-all modules named utils.py or helpers.py. That practice causes trouble in a few ways. These names say nothing about what’s inside, so contributors can’t predict where to add a new function and end up piling unrelated code together.

These modules accumulate imports from across the codebase and commonly turn into circular-import hotspots. Worst of all, once everyone depends on them, even small changes risk breaking distant callers.

Domain-named subpackages scale better than a junk drawer. Each one is a package in its own right. Subpackages like package_name/core/, package_name/api/, and package_name/cli/ each carry a clear responsibility. They can expose a narrow public surface through __init__.py and keep their dependencies flowing in one direction.

Inside them, use absolute and relative imports deliberately, defaulting to absolute ones for clarity. With these three layers in mind, you can see how real projects put them to work.

A Library: Small Statistics Helper

Say that you’re writing a small statistics helper called statkit. Because a library exists only to be imported and never run, it shows the layout with the fewest moving parts. It’s also a natural candidate for publishing to PyPI, which is why it uses a src/ layout.

Here’s the tree for a hypothetical statkit library that ships statistics functions in separate modules:

statkit/
│
├── src/
│   └── statkit/
│       ├── __init__.py        ← API: mean, median, stdev, pearson, spearman
│       ├── correlation.py     ← Define: pearson, spearman
│       ├── descriptive.py     ← Define: mean, median, stdev
│       └── py.typed           ← PEP 561 marker, ships type hints
│
├── tests/
│   ├── test_correlation.py    ← Tests for correlation.py
│   └── test_descriptive.py    ← Tests for descriptive.py
│
├── docs/
│
├── LICENSE
├── pyproject.toml
└── README.md

Beyond the [build-system] and [project] boilerplate, the src/ layout needs only the single table you saw earlier, which points the build backend at the package under src/:

[tool.setuptools.packages.find]
where = ["src"]

Because pure libraries aren’t runnable, you have no __main__.py and no [project.scripts] table. The public API surface lives in __init__.py, which re-exports functions like mean(), median(), stdev(), pearson(), and spearman(). Listing them in the __all__ attribute keeps callers from reaching into descriptive.py or correlation.py directly.

Here’s what that looks like:

from statkit.descriptive import mean, median, stdev
from statkit.correlation import pearson, spearman

__all__ = ["mean", "median", "stdev", "pearson", "spearman"]

Here, two files matter more than in the application examples. A LICENSE is effectively required. PyPI accepts uploads without one, but no downstream project can legally depend on code that has no license.

An empty py.typed file inside the package, defined by PEP 561, tells type checkers like mypy and Pyright that the library ships its own type hints. Without it, type checkers silently ignore your annotations and treat every export as Any.

When you’re ready to share your library, the guide on how to publish a package to PyPI picks up where this layout leaves off.

A CLI Application: Weather Report Tool

A weather report tool is a good example of a small CLI, and it shows the entry-point conventions in a flat application layout:

weatherly/
│
├── weatherly/
│   │
│   ├── sources/
│   │   ├── __init__.py
│   │   └── ...              ← API clients, one per provider
│   │
│   ├── __init__.py
│   ├── __main__.py          ← Enables python -m weatherly
│   ├── cli.py               ← Argument parsing and main()
│   └── forecast.py          ← Fetch and format the forecast
│
├── tests/
│
├── pyproject.toml
└── README.md

The weatherly command comes from a single table in pyproject.toml:

[project.scripts]
weatherly = "weatherly.cli:main"

In this example, the entry-point string "weatherly.cli:main" is an import path, not a path on disk, so moving the package into src/weatherly/ for a src/ layout wouldn’t change it. You can make this move if the project grows and you want the tests to run against an installed copy.

The one practical consequence of migrating to src/ is that python -m weatherly from the project root stops working until an editable install like python -m pip install -e . puts the package back on the import path.

A Django Project: Personal Portfolio Site

A personal portfolio site is a comfortable size for a Django project. Here, Django’s conventions assume the flat layout, and the framework’s own tooling generates most of this tree:

portfolio/
│
├── apps/
│   ├── blog/
│   ├── contact/
│   └── projects/            ← Portfolio entries
│
├── portfolio/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
│
├── static/
│
├── templates/
│
├── tests/
│
├── manage.py
├── pyproject.toml
└── README.md

Running django-admin startproject puts manage.py at the root, along with the inner project package and its settings.py, urls.py, asgi.py, and wsgi.py. Then python manage.py startapp creates each app next to manage.py by default.

Grouping those apps under an apps/ directory is a convention that many larger projects adopt to keep the root tidy once they outgrow two or three apps. It isn’t a free move, though: Because it changes each app’s import path, you need to update the app’s AppConfig.name and its INSTALLED_APPS entry so Django can still find it.

Django apps are Python packages in their own right, so the same __init__.py rules apply. A src/ layout is unusual for Django projects, but possible.

For everything past the layout, the Django tutorials cover the framework itself, and the walkthrough on how to set up a Django project starts you from scratch.

A Flask Project: Personal Blog

A personal blog suits Flask, where the package’s __init__.py does real work instead of merely re-exporting names. As with Django, Flask projects follow the framework’s flat convention.

Here’s the directory tree for a flat Flask layout:

bloggy/
│
├── bloggy/
│   │
│   ├── static/
│   │
│   ├── templates/
│   │   ├── auth/
│   │   ├── posts/
│   │   └── base.html
│   │
│   ├── __init__.py          ← Application factory
│   ├── auth.py              ← Auth blueprint
│   ├── db.py
│   └── posts.py             ← Posts blueprint
│
├── tests/
│
├── pyproject.toml
└── README.md

Here, the __init__.py file is an application factory that creates the Flask app and registers blueprints. Each blueprint module, like auth.py and posts.py, owns a slice of the URL space and a matching subdirectory under templates/.

The official Flask tutorial uses this same flat layout, with blog.py in place of posts.py. Real projects often keep non-Python data files like schema.sql next to db.py.

To go beyond the layout, check out the guide on how to structure a scalable Flask project and the broader Flask tutorials.

A FastAPI Project: Book-Catalog API

A book-catalog API is a natural fit for FastAPI, where an APIRouter provides the same modularity that Django apps and Flask blueprints do.

Here’s the directory tree for a FastAPI project:

bookapi/
│
├── bookapi/
│   │
│   ├── internal/
│   │   ├── __init__.py
│   │   └── admin.py         ← Admin-only endpoints
│   │
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── authors.py       ← Author endpoints
│   │   └── books.py         ← Book endpoints
│   │
│   ├── __init__.py
│   ├── dependencies.py      ← Auth and DB session helpers
│   └── main.py              ← FastAPI app, includes routers
│
├── tests/
│
├── pyproject.toml
└── README.md

The FastAPI bigger-applications tutorial uses exactly this shape, where main.py builds the app and pulls in each router.

Unlike the CLI example and the GUI app you’ll see next, this project has no __main__.py. You launch a FastAPI app by pointing an ASGI server like Uvicorn at bookapi.main:app, not by running the package as a module.

Every subpackage, like routers/ and internal/, gets its own __init__.py so that the relative imports inside each module resolve correctly.

A flat layout works well for a microservice deployed straight from a repository, while src/bookapi/ makes sense once you start shipping a wheel or a container. If FastAPI is new to you, then the tutorial on how to get started with FastAPI covers the framework behind this layout.

A GUI Application: Desktop Notes App

A desktop notes app rounds out the examples, and GUI apps add a wrinkle that the others don’t: They usually split the package along an architectural pattern. The common choices are MVC (Model-View-Controller), MVP (Model-View-Presenter), and MVVM (Model-View-ViewModel). All of them keep input handling, state, and rendering testable in isolation.

The example below is a PyQt or PySide app that uses MVC, but the same shape works for MVP or MVVM if you rename controllers/ to presenters/ or viewmodels/. Here’s the layout sketch:

notely/
│
├── notely/
│   │
│   ├── controllers/
│   │   ├── __init__.py
│   │   └── ...              ← Input handlers, app coordination
│   │
│   ├── models/
│   │   ├── __init__.py
│   │   └── ...              ← Note data and persistence
│   │
│   ├── resources/
│   │   ├── icons/
│   │   ├── translations/
│   │   └── __init__.py
│   │
│   ├── views/
│   │   ├── ui/              ← Qt Designer .ui files
│   │   ├── __init__.py
│   │   └── ...              ← Screens, dialogs, main window
│   │
│   ├── __init__.py
│   ├── __main__.py
│   └── app.py               ← Wires models, views, controllers
│
├── tests/
│
├── pyproject.toml
└── README.md

Two more GUI-specific twists go beyond the CLI conventions. The first is assets. Keep content like icons and translations in resources/, and keep Qt .ui files with the views they define under views/ui/.

In both cases, those directories live inside the importable package so that they travel with the code when you distribute the app. Load them through importlib.resources.files() rather than relative paths built from __file__, which are unreliable inside zip imports and frozen bundles like PyInstaller, py2app, and cx_Freeze.

In pyproject.toml, two tables back these choices. One table gives the app a launch command, and the other declares resources/ and the .ui files as package data so the build includes them:

[project.scripts]
notely = "notely.app:main"

[tool.setuptools.package-data]
notely = ["resources/**/*", "views/ui/*.ui"]

The second twist is distribution. Desktop apps that aren’t scaffolded by a tool follow no single convention. Spyder keeps a flat layout, while Calibre uses a src/ layout, and each has its own build pipeline: Calibre freezes the interpreter, and Spyder builds conda-based installers. Briefcase, by contrast, bootstraps projects as src/ layouts from the start.

The layout choice depends as much on your packaging tool as on your GUI framework. To dig into PyQt itself, check out the GUI Programming With PyQt learning path. With these concrete examples on the table, a side-by-side comparison brings the pattern into focus.

Comparing the Layouts at a Glance

Lined up by project type, the examples reveal both shared patterns and genuine differences:

Read down the columns, and the pattern is clear. Every application project uses the flat layout, while the library reaches for src/. Every runnable project funnels execution through a thin, well-defined entry point.

What changes from one project to the next is how each one splits its code—whether into Django apps, Flask blueprints, FastAPI routers, or GUI layers—and how it reaches its users. The skeleton stays the same, and your framework determines what you hang on it.