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 (50,919
api (1,616
layout (172
modular (113
structure (28

Find Open Source By Browsing 7,000 Topics Across 59 Categories