Python Project Layout Conventions — ELI5

Imagine moving into a new house where every room is labeled: kitchen, bedroom, bathroom. You never wonder where to cook or sleep. A Python project layout does the same thing for code.

Without conventions, a project looks like a junk drawer. Tests sit next to config files, scripts tangle with library code, and new contributors waste hours figuring out where things live. With a clear layout, everyone opens the right folder on instinct.

The most common pattern is called the src layout. Your actual code goes inside a src/ folder, tests go in tests/, and project settings live in a pyproject.toml at the root. It looks like a house blueprint: front door here, rooms there, utilities in the basement.

Another popular choice is the flat layout, where the package folder sits directly at the project root. Smaller projects like this because it is simpler, but it can accidentally mix installed code with development files.

Why does it matter? Because when someone joins your project — or when future-you returns after six months — a predictable layout removes guesswork. You spend brain power on the problem, not on finding the file.

Pick one layout, stick with it across your projects, and document the choice. Consistency beats perfection every time.

The one thing to remember: A clear folder structure is the cheapest investment that saves the most confusion over a project’s lifetime.