Python Project Structure: src vs Flat Layout and Tests
November 11, 2026 · 12 min read
Python Project Structure: Flat vs src Layout, pyproject.toml and Tests
A good python project structure puts your importable code in one package folder, project settings in pyproject.toml at the root, and tests in a top-level tests/ folder. The README, LICENSE and docs/ sit beside them. Use the src layout for anything you install or test in CI, and a flat layout for a simple script.
What Does a Modern Python Project Structure Look Like?
Here's a minimal installable project, the modern Python 3 project structure that PyPA and pytest both document. The comments say what each entry is for, and you can copy the tree straight into your own notes.
skycast/ # project root, usually the git repo
├── pyproject.toml # metadata, dependencies, build backend, tool settings
├── README.md # what the project does and how to install it
├── LICENSE # the full license text
├── .gitignore # keeps .venv and __pycache__ out of git
├── docs/ # longer documentation
├── src/
│ └── skycast/ # the import package: import skycast
│ ├── __init__.py
│ └── forecast.py
└── tests/
└── test_forecast.py # tests live outside the package
Two names are in play here. The outer skycast/ is the project root, the folder you clone. The inner src/skycast/ is the import package, the name your code uses in import skycast. They often match, but they don't have to.
Import names can't contain hyphens, so a project called example-app ships a package called example_app. PEP 8 asks for short, all-lowercase package names and discourages underscores. A single word like skycast avoids the question entirely.
Flat Layout vs src Layout: Which Should You Use?
The two layouts differ in one folder. In the flat layout the package sits directly in the project root. In the src layout it sits one level down, inside src/.
flat layout src layout
skycast/ skycast/
├── pyproject.toml ├── pyproject.toml
├── skycast/ ├── src/
│ ├── __init__.py │ └── skycast/
│ └── forecast.py │ ├── __init__.py
└── tests/ │ └── forecast.py
└── test_forecast.py └── tests/
└── test_forecast.py
That extra folder matters because Python usually puts the current directory first on the import path. Run Python from a flat project's root and import skycast loads the folder in front of you, not the copy you installed. Your tests can pass locally even when the built package is missing a file.
The PyPA discussion of src vs flat layout says the src layout helps prevent accidental use of the in-development copy. The pytest good practices page goes further. It strongly suggests a src layout, especially with pytest's default prepend import mode.
The cost is an install step. PyPA notes that the src layout needs the project installed before its code runs, while the flat layout doesn't. Most people use an editable install, which picks up your edits without reinstalling:
python -m venv .venv
source .venv/bin/activate # on Windows: .venv\Scripts\activate
python -m pip install --editable .
Here's how the two compare in practice:
| Flat layout | src layout | |
|---|---|---|
| Runs without an install step | Yes | No, install it first |
| Tests import the installed package | Not by default | Yes |
| Tests the built package, not your working copy | Not without extra setup | Yes, with a regular (non-editable) install |
Created by plain uv init | No | Yes |
| Good fit | Scripts, notebooks, small apps | Libraries, CLIs, anything in CI |
We prefer the src layout for anything you'll install, publish or test in CI. The flat layout is fine for a notebook folder or a single-purpose script. One limitation to accept: per PyPA, a src-layout command-line tool can't run straight from the source tree, so you install it first.
Where pyproject.toml Fits in the Structure of a Python Project
pyproject.toml lives at the project root and replaces most of what setup.py, setup.cfg and a hand-kept dependency list used to do. This one describes the skycast package above:
[build-system]
requires = ["hatchling >= 1.26"]
build-backend = "hatchling.build"
[project]
name = "skycast"
version = "0.1.0"
description = "Print a short weather forecast for a city"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
dependencies = [
"httpx>=0.27",
]
[project.scripts]
skycast = "skycast.cli:main"
[dependency-groups]
dev = ["pytest"]
Here's what each table does:
[build-system]names the build backend that turns your source into an installable package. Hatchling findssrc/skycast/on its own.[project]holds the metadata. Thenamefield is required, andversionis required too unless you mark it dynamic.[project.scripts]creates askycastcommand that callsmain()inskycast/cli.pyonce the package is installed. You'll add thatcli.pyfile in the multi-module layout further down.[dependency-groups]lists tools you need while developing, such as pytest, without making users install them.
The PyPA guide to writing pyproject.toml covers every field. For new projects it says to use the [project] table and keep setup.py only for programmatic configuration, such as building C extensions.
So do you still need setup.py? Usually not. The file itself isn't deprecated, but running python setup.py install is. Use python -m pip install . instead, and python -m pip install --editable . in place of setup.py develop.
Runtime dependencies now go in [project].dependencies. A requirements.txt or a lock file still has a job: pinning the exact versions an app deploys with. Building and uploading to PyPI is a separate topic, and PyPA's packaging tutorial walks through it.
How to Structure a Python App or Script Project
Not every project is a library, and the Python project structure for an app can be much lighter. A script you run on a schedule, a small web service or a data job may never be installed anywhere. For those, a flat layout keeps things short:
price-alerts/
├── pyproject.toml # dependencies and Python version, no build system
├── README.md
├── main.py # the entry point: python main.py
├── config/
│ └── settings.toml # settings you edit, kept out of the code
└── data/ # input files, usually git-ignored
This matches what uv init --no-package generates, minus the folders: a pyproject.toml with no build system, a main.py, a README and a .python-version pin. Plain uv init goes the other way. Per uv's docs as of November 2026, it defines a build system and puts the code in src/<project_name>/, even for applications.
Once main.py outgrows one file, turn the code into a package and add a __main__.py. The Python docs explain that this file runs when you invoke the package with python -m:
# price_alerts/__main__.py
from price_alerts.cli import main
main()
Now python -m price_alerts starts the app. The docs recommend keeping __main__.py this short and importing the real work from other modules, so that code stays easy to test. Keep config/, data/ and any notebooks outside the package unless the package genuinely ships them.
Watch your file names in a flat project. The folder holding the script you run comes first on the import path. A file you name random.py, email.py or logging.py therefore hides the standard library module of the same name. Python 3.13 and later name the clash in the error message, but older versions just report a confusing missing attribute.
Structuring a Python Package or CLI With Several Modules
As a package grows, split it by responsibility and mirror that split in tests/. Here's skycast with a command-line interface and a subpackage:
skycast/
├── pyproject.toml
├── README.md
├── src/
│ └── skycast/
│ ├── __init__.py # the public API: what users import
│ ├── __main__.py # lets python -m skycast work
│ ├── cli.py # argument parsing, calls into the rest
│ ├── formatting.py
│ └── forecast/
│ ├── __init__.py
│ ├── models.py
│ └── sources.py
└── tests/
├── conftest.py # shared pytest fixtures
├── test_cli.py
├── test_formatting.py
└── forecast/
├── test_models.py
└── test_sources.py
Name modules after what they do, not after the kind of code inside them. A forecast/sources.py tells a newcomer more than a helpers.py, and it doesn't turn into a drawer for everything that has no other home. Keep cli.py thin, too. It parses arguments and hands off to functions in the rest of the package, which you can test without a terminal:
# src/skycast/cli.py
import argparse
from skycast.formatting import render_forecast
def main() -> None:
parser = argparse.ArgumentParser(prog="skycast")
parser.add_argument("city")
args = parser.parse_args()
print(render_forecast(args.city))
The [project.scripts] entry from the previous section points at this main() function. After an install, typing skycast London in a terminal runs it.
Does every folder need an __init__.py? For a normal package, yes. The Python tutorial says these files make Python treat a directory as a package, unless you use a namespace package. Namespace packages (PEP 420) are an advanced feature for splitting one package across several distributions, so add __init__.py to every folder under src/skycast/.
Where Should Tests Go in a Python Project?
Put them in a tests/ folder at the project root, next to src/, not inside the package. That's the first layout pytest documents, and it means your tests import the installed package the way your users will. Mirror the package's folders inside tests/ so each test file is easy to find. Go does the reverse and keeps test files beside the code, as our Go project structure guide shows.
pytest collects files named test_*.py or *_test.py. Inside them it runs functions that start with test, plus test methods on classes whose names start with Test. Shared fixtures go in conftest.py.
pytest recommends the importlib import mode for new projects. From version 9, pytest reads a native [tool.pytest] table in pyproject.toml. Versions 6 to 8 only read [tool.pytest.ini_options], which pytest 9 still accepts:
[tool.pytest]
addopts = ["--import-mode=importlib"]
testpaths = ["tests"]
With that in place, install the project in editable mode along with the dev group, then run the suite. The --group option needs pip 25.1 or later:
python -m pip install --editable . --group dev
pytest
If you'd rather not install at all, pytest's pythonpath setting can add src to the import path instead. We still prefer the editable install, because it tests the package the way it's actually built.
README, docs/, LICENSE and .gitignore at the Project Root
These files belong at the top level, beside pyproject.toml, because GitHub, PyPI and your build tools look for them there.
- README.md is what GitHub shows on your repository page. Setting
readme = "README.md"inpyproject.tomlalso makes it the project description on PyPI. Our README Markdown guide covers what to put in it. - docs/ holds longer documentation as Markdown files. If you build a site from them with MkDocs,
mkdocs.ymlsits at the root and points atdocs/, as our MkDocs Markdown guide explains. For API pages generated from your code, see our guide to the Sphinx docstring format. - LICENSE holds the full license text, and the
licensefield inpyproject.tomlnames it with an SPDX identifier such asMIT. - .gitignore keeps the virtual environment,
__pycache__folders and build output out of git. The .gitignore generator has a Python template to start from.
You can draft the README and the docs pages in our Markdown editor. It's free, runs in the browser with no account needed, and shows a live preview beside your Markdown as you type.
Draw Your Python Folder Structure as a Tree
A README often includes a drawing of the Python project structure, so contributors know where things go. Write it as a plain-text tree inside a fenced code block tagged text, exactly like the examples on this page. Keep it to the folders that matter and skip generated ones like .venv. For a project that already exists on disk, the tree command can print the directory tree for you.
Drawing the box characters by hand gets tedious. The directory tree generator builds the tree from an indented list or a list of paths like this:
skycast/pyproject.toml
skycast/README.md
skycast/src/skycast/__init__.py
skycast/src/skycast/cli.py
skycast/tests/test_cli.py
You can also pick or drop a folder, and it reads the file paths in your browser without uploading anything. It skips folders like node_modules, .git and build output, then renders box-drawing, ASCII, a Markdown list or tree-style text. It only draws your Python folder structure. It doesn't create the files or scaffold the project for you.
A clear python project structure comes down to a few choices. Pick src or flat, keep one pyproject.toml at the root, put tests beside the package, and leave the README and docs where tools expect them. Start with the tree that matches your project, then document it in your README so the next person knows where things go. The directory tree generator draws that layout from a list of paths or a folder you pick.