Skip to content

Cookiecutter Python Project

Actions Status Actions Status

Cookiecutter template to generate python projects following the best practices gathered over the time.

Sadly it's heavily focused on Github. If you want to use another git web application or CI providers, please open an issue.

The template will:

  • Initialize the git repository with the correct github remote and a useful gitignore.

  • Configure the project layout following the src and domain driven design structures.

  • Configure the program dependencies to be handled by pip-tools.

  • Configure a Github Action to hourly update the dependencies.

  • Configure the program documentation using MkDocs, with some niceties like generating a reference page directly from the docstrings.

  • Generate a Makefile to gather the common developer operations, go to the contributing page to look at the most important.

  • Configure the versioning to follow semantic versioning: Assuming you use commit messages following the conventional commits guidelines, you'll be able to automatically bump the version and generate the changelog without human interaction with commitizen.

  • Configure the command line interface. Adding the --version argument to show the current version.

  • Configure management of the program configuration using a yaml file:

    • Configure the installation to create the directory containing the configuration file and copy the template of the default yaml file.
    • Configure the Config object that allows the fetching and setting of the configuration in a friendly dotted way.
  • Create a helper function to output the version of the program, Python and the operative system, useful for debugging user issues.

  • Configure the static analysis tools:

    • Configure Pytest as test framework. Set up the format, directories to ignore and the slow and secondary marks.
    • Configure Black for automatic format and check the code styling.
    • Configure isort to automatically sort the import statements.
    • Configure flakehell to check errors in your code.
    • Configure Mypy to check the typing of your code.
    • Configure Safety to check dependencies that have vulnerabilities.
    • Configure Bandit to check for vulnerabilities in your code.
    • Configure Markdownlint to flag errors, bugs or stylistic errors in markdown files.
  • Configure Github's project:

    • Create the repository.
    • Create the issue and pull request templates.
    • Configure Dependabot to notify on outdated dependencies.
    • Create the secrets to publish to PyPI.
    • Configure the Security advisories.
  • Configure the continuous integration pipelines:

  • Configure the continuous deployment pipelines:

    • Automatically deploy the documentation static website on each push to master.
    • Automatically build the python packages and publish them to PyPI.
  • Configure the pre-commits.

  • Configure the base typing
  • Set the license to GPLv3.


We assume you are comfortable with some tools:

  • cruft or cookiecutter to generate the template.
  • pass: Used to load the sensitive data such as the github credentials.
  • commitizen: Used to bump the version and make the releases.

To create a new project use:





For guidance on setting up a development environment, and how to make a contribution to cookiecutter-python-project, see Contributing to cookiecutter-python-project.

Last update: 2020-12-28