Your Cookiecutter Is Wrong
My talk from EuroPython 2025
Abstract
Starting a new Python project comes with many decisions:
- Flat layout or src layout?
- Where will tests live?
- Packaged application or not?
- What will be the entry point of your application?
- One top-level package or Django-like apps?
- How will the application be installed?
- pip, uv, or Poetry integration?
There’s no single standard for a Python project structure, and popular tools offer a lot of flexibility: uv can create a library, an application, or a packaged application, pytest documents two possible test layouts and supports three import modes, and mypy implements its own import mechanism.
If you’re starting a library, you can take inspiration from open-source champions, but applications are usually proprietary. Many Cookiecutter templates exist online, but which one should you choose? A common approach is to clone an existing project your company uses, but in my experience, this isn’t always the best idea.
I’ll point out common mistakes to avoid. We’ll explore the key decisions and weigh the benefits and drawbacks of each option. My goal isn’t to sell you on my favorite directory structure. Instead, I’ll help you choose what suits your use case best, ensuring that your choices play well with each other.
Slides
