Skip to main content

Integration of Cookiecutter project templates into PyScaffold (see:

Project description

Built Status ReadTheDocs Coveralls PyPI-Server Monthly Downloads


Extension that combines the flexibility of Cookiecutter templates with the power of PyScaffold.

Cookiecutter is a flexible utility that allows the definition of templates for a diverse range of software projects. On the other hand, PyScaffold is focused in a good out-of-the-box experience for developing distributable Python packages (exclusively). Despite the different objectives, it is possible to combine the power of both tools to create a custom Python project setup.


This extension can be directly installed with pip:

pip install pyscaffoldext-cookiecutter

Or, if you prefer pipx:

pipx install pyscaffold  # if you haven't installed pyscaffold yet
pipx inject pyscaffold pyscaffoldext-cookiecutter

Note that, after the installation, putup -h will show a new option --cookiecutter TEMPLATE. Use this option to point out which template you want to use (path or url). The file structure created by Cookiecutter will be refined by PyScaffold afterwards. For example:

putup my-proj1 --cookiecutter ~/my-templates/default
putup my-proj2 --cookiecutter gh:something/from-github

Please refer to Cookiecutter documentation for more details on possible URLs and abbreviations.

An additional option --cookiecutter-params is also added, so you can have more control over the values Cookiecutter uses when rendering the templates (PyScaffold will not run Cookiecutter’s interactive prompt). This option takes the form of a space separated list of NAME=VALUE arguments as showed in the example bellow:

putup mypkg \
  --cookiecutter gh:pyscaffold/cookiecutter-pypackage \
  --cookiecutter-params command_line_interface=Argparse use_pytest=y

Check the cookiecutter.json file in the repository (or directory) of the template you are using to see the available parameters. Please notice PyScaffold already add some default parameters, as indicated in the section Suitable Templates bellow.

Cookiecutter templates with PyScaffold

The following example shows how to create a new package named mypkg, that uses a Cookiecutter template, but is enhanced by PyScaffold’s features:

putup mypkg --cookiecutter gh:pyscaffold/cookiecutter-pypackage

This is roughly equivalent to first create a project using the Cookiecutter template and convert it to PyScaffold afterwards:

cookiecutter --no-input gh:pyscaffold/cookiecutter-pypackage project_name=mypkg
putup mypkg --force

Suitable templates

Note that PyScaffold will overwrite some files generated by Cookiecutter, like, the file under the package folder and most of the docs folder, in order to provide setuptools_scm and sphinx integration. Therefore not all Cookiecutter templates are suitable for this approach.

Ideally, interoperable templates should focus on the file structure inside the src folder instead of packaging or distributing, since PyScaffold already handles it under-the-hood. This also means that your template should adhere to the src-layout if you want to generate files within your Python package.

In addition, PyScaffold runs Cookiecutter with the --no-input flag activated and thus the user is not prompted for manual configuration. Instead, PyScaffold injects the following parameters:

full_name => same as author
project_name => the name of the folder where the project will be generated
repo_name => same as project_name
package_name => putup's --package (as in `import`)
namespace => putup's --namespace (if any)
installable_name => putup's --name (an installable name, like in PyPI/pip install)
project_short_description => putup's description
release_date => equivalent to the day you are running putup
year => equivalent to the year you are running putup

Any extra parameter should be passed using the --cookiecutter-params option.

Accordingly, the template file structure should be similar to:

└── {{cookiecutter.project_name}}/
    └── src/
        └── {{cookiecutter.package_name}}/
            └── ...

See Cookiecutter for more information about template creation.

Making Changes & Contributing

This project uses pre-commit, please make sure to install it before making any changes:

pip install pre-commit
cd pyscaffoldext-cookiecutter
pre-commit install

It is a good idea to update the hooks to the latest version:

pre-commit autoupdate

Please also check PyScaffold’s contribution guidelines,


This project has been set up using PyScaffold 4.0a2. For details and usage information on PyScaffold see

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyscaffoldext-cookiecutter-0.1.tar.gz (26.4 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page