Welcome to pythontemplate’s documentation!

Build Status Documentation Status Updates

Cookiecutter template for a Python package.

GitHub repo:
Free software:
GNU General Public License v3


  • Testing setup with unittest and python setup.py test or py.test
  • Tox testing: Setup to easily test for Python 3.5 (WIP)
  • Sphinx docs: Documentation ready for generation with, for example, ReadTheDocs
  • Command line interface using Click
  • Support for implicit namespaces from PEP420
  • Gets you started for a web application (optional)


Install the latest Cookiecutter if you haven’t installed it yet (this requires Cookiecutter 1.4.0 or higher):

pip install -U cookiecutter

Generate a Python package project:

cookiecutter https://github.com/cblegare/cookiecutter-py.git


  • Create a repo and put it there.
  • Install the dev requirements into a virtualenv. (pip install -r requirements/dev.txt)
  • Edit the requirements.txt file that specifies the packages you will need for your project and their versions. For more info see the pip docs for requirements files.

Known issues


Be carefull with namespace packages using the implicit namespace mechanism. Some tools are not fully compliant yet.

Namespace package and editable installations should be fixed with setuptools 31 and Python 3.5:

You may also have issues with imports from external tools. Most of them are or will be fixed in with sphinx 1.5, pytest 2.5 and pylint 2.0 (not released yet).

Using latest versions, only pylint still has issues with implicit namespaces at the time of this writing.

Fork This / Create Your Own

If you have differences in your preferred setup, I encourage you to fork this to create your own version. Or create your own; it doesn’t strictly have to be a fork.


It’s up to you whether or not to rename your fork/own version. Do whatever you think sounds good.