Skip to content

Cookiecutter template for an idiomatic Python project driven by Makefile


Notifications You must be signed in to change notification settings


Repository files navigation


Cookiecutter template for a Python package.

The boilerplate Python project that aims to create facility for maintaining of the package easily. It considering tools for building, testing and distribution.

Get Started

This template provides a basic structure for an idiomatic Python package with a convenient Makefile-facility and additional helpers.

Template can be configured using Cookiecutter's CLI or by altering parameters directly in cookiecutter.json.


There are a couple of tools for building, packaging, documentation and so on, that must be installed.

  • GNU sed (brew install gnu-sed for macOS),
  • ripgrep (optionally),
  • awk,
  • Docker,
  • Virtualenv,
  • Sphinx (for sphinx-build and sphinx-apidoc).

To check availability of main tools just type make or make doc.


  • To get help about available Makefile targets type:

    make help

Creating the virtual environment

  1. Compile Pip requirements from to requirements.txt using pip-tools (via Docker):

    make requirements
  2. Create the new virtual environment based on requirements.txt and requirements-test.txt:

    make venv
  3. Install the package into a virtual environment in so-called "development mode":

    source .venv/bin/activate
    make install
    # ...hard working here...
    make uninstall

Testing the package

Pytest is used as a test tool by default.

  • To run tests type (within a virtual environment):

    make check

Building the package from scratch

  • Create a source distribution (tarball with sources):

    make sdist
    ls -al dist/*.tar.gz
  • Create a binary (wheel) distribution:

    make dist
    ls -al dist/*.whl

Dealing with containers

  • Display system-wide information:

    make docker-info
  • Show all images, containers and volumes:

    make docker-stats
  • Build the image according to Dockerfile:

    make docker-build
  • Run temporary container in an interactive mode:

    make docker-run
  • Remove all unused images, built containers and volumes:

    make docker-clean

Documenting the project using Sphinx

  1. Build an API documentation:

    make apidoc
  2. Build the documentation as a standalone HTML files:

    make html
    open doc/_build/html/index.html
  • Clean the project's directory (precompiled and temporary files):

    make clean
  • Clean the project's build output (eggs, distributions, builds):

    make distclean
  • Delete almost everything (including virtual environment):

    make mostlyclean


Cookiecutter template for an idiomatic Python project driven by Makefile








No packages published