ProjectFileAndDirectoryLayout
This wiki is in the process of being archived due to lack of usage and the resources necessary to serve it — predominately to bots, crawlers, and LLM companies. Edits are discouraged.
Pages are preserved as they were at the time of archival. For current information, please visit python.org.
If a change to this archive is absolutely needed, requests can be made via the infrastructure@python.org mailing list.
The topic of how to structure your project invokes lots of opinions. Generally speaking, the relatively agreed guidelines include:
- if the project is a single source file, put it in the top level.
- if you have tests, put them in a tests/ subdirectory (even if the project is a single source file), or if you have subdirectories and prefer to keep unit tests with code, put them there.
- if you have an executable script to run your project, put it in a bin/ subdirectory, without the .py suffix even if it's a Python script
- if you have many source files, create a subdirectory with the name of the project, and start populating there
- include a doc/ directory (you have docs, right?)
- create module directories as needed
These guidelines are partly convention, partly because they align well with Python packaging tools.
The Python tutorial shows an example of a more complex layout: https://docs.python.org/3/tutorial/modules.html#packages
There are many many other places that describe a layout, not all agreeing. Here are a couple:
packaging chapter of Dive Into Python 3 for some useful information.