Your Cookiecutter is Wrong

Starting a new Python project comes with many decisions:

• Flat layout or src layout?
• What will be the entry point of your application?
• Where will tests live?
• Packaged application or not?
• One top-level package or Django-like apps?
• Absolute imports or relative ones?
• How will the application be installed?
• Docker: for runtime, development, or both?
• How to coexist with other technologies?

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.

We’ll explore the key decisions and weigh the benefits and drawbacks of each option. I’ll point out common mistakes to avoid. 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.