Awesome Open Source
Awesome Open Source

.. image:: :target: .. image:: :target: ../master/LICENSE


Show how to structure a Python project.

Inspired by

Great resources


Please browse this blog post for a good summary of recommendatios and templates:

Python 2 or 3?

  • Develop your code under Python 3, test it for both Python 2 and Python 3 but consider Python 3 to be the default today.

Split your code into packages, modules, and functions

  • All code should be inside some function (except perhaps if __name__ == '__main__':).
  • Split long functions into smaller functions.
  • If you need to scroll through a function over several screens, it is probably too long.
  • Functions should do one thing and one thing only.
  • Hide internals with underscores.
  • Organize related functions into modules.
  • If modules grow too large, split them.
  • Import from other modules under somepackage/ using from .somemodule import something.
  • Do file I/O on the "outside" of your code, not deep inside.

Classes vs. functions

  • Do not overuse classes.
  • Prefer immutable data structures.
  • Prefer pure functions.


  • Give the subdirectory the same name as your package.
  • Before you name your package, check that the name is not taken on (you may want to upload your package to PyPI one day).


  • In somepackage/ define what should be visible to the outside.
  • Use


Dependency management

  • Package dependencies for developers should be listed in requirements.txt.
  • Alternatively, consider using
  • Package dependencies for users of your code (who will probably install via pip) should be listed in

Code style

Type checking

Share your package


I used to recommend reStructuredText for READMEs in contrast to Markdown but PyPI no longer requires reStructuredText. You can use Markdown as noted on under "How can I upload a project description in a different format?".

Example shown here:

Suggestions? Corrections? Pull requests?

Yes please!

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (55,393
api (1,757
layout (181
modular (121
structure (29