# cookiecutter-pylibrary, a template aimed squarely at packaging mistakes > cookiecutter-pylibrary is a Cookiecutter template for Python libraries that comes with tox environments, a test matrix, Sphinx docs ready for ReadTheDocs, coverage tracking, isort and bumpversion configuration and a check environment that validates your README and MANIFEST.in. It is more involved than the usual template, and it was built to answer a specific set of packaging complaints. **ionelmc/cookiecutter-pylibrary** — Enhanced cookiecutter template for Python libraries. - Repository: https://github.com/ionelmc/cookiecutter-pylibrary - Stars: 1,300 · Forks: 207 - Language: Python - License: BSD-2-Clause - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/ionelmc-cookiecutter-pylibrary ## The template exists because of two blog posts about packaging The reason this template is different from the usual one is stated at the top of the README, in a section of notes. It is largely designed to address a blog post about packaging Python libraries, and it will save you from packaging pitfalls, and both are the author's own posts from 2014. That origin explains the shape of the thing. A template that is aimed at a general audience would give you a project skeleton and stop. This one is aimed at the specific set of decisions that go wrong when you publish a library, and it ships a decision for each of them, pre-made. The README also points to a bare library built from the template, python-nameless, if you want to see what the result looks like without generating anything. And for the case where you are building a web application rather than a library, it points at django-docker instead, which is an honest scoping of what this template is for. The README describes itself as an all inclusive sort of template, and the feature list backs that up. There is a choice of various licenses, Tox for managing test environments, Pytest or Nose for testing, optional support for creating a tests matrix out of dependencies and Python versions, Travis-CI and AppVeyor for continuous testing, Coveralls or Codecov for coverage tracking, documentation with Sphinx ready for ReadTheDocs, and configurations for isort and bumpversion with bump2version required. There is also support for C extensions, including coverage measurement for the C code, and a tox environment named check that validates the packaging itself. That check environment checks if your README.rst is valid and checks if the MANIFEST.in has any issues, which is the piece that saves the most time in practice, because a broken MANIFEST.in is discovered at install time by users rather than at build time by you. ## Generating a project, and the fields you get asked for The requirements are deliberately minimal. Cookiecutter is needed just for creating the project, Tox for running the tests, and Setuptools for building the package and wheels. The README suggests installing setuptools and pip first, since setuptools is widely available, and then the bare minimum: ```shell pip install tox cookiecutter ``` The generation command is the standard Cookiecutter GitHub shorthand: ```shell cookiecutter gh:ionelmc/cookiecutter-pylibrary ``` What follows is a list of fields, and the README uses a table for them. Some are author identity, some are naming, some change the layout. The author fields are full_name, which defaults to Ionel Cristian Maries and is used in AUTHORS.rst and setup.py, email, also used in AUTHORS.rst and setup.py, and website, used in AUTHORS.rst. The README notes that fields which work together usually use the same prefix, and that the first two can be set in your ~/.cookiecutterrc config file so you do not retype them for every project. The naming fields are where the confusion lives, because Python projects have several names. repo_username and repo_name identify the repository, and repo_name is also the root directory name. package_name is the name you would import, distribution_name is the name you would pip install, and module_name is the implementation module inside the package, defaulting to core on the assumption that there will be one. project_name is the verbose name used in headings across the docs and readme, and project_short_description is the one line description used in README.rst and setup.py. The hosting field is repo_hosting_domain, defaulting to github.com. The README says to use "no" for no hosting, in which case various links disappear, and that you can also use gitlab.com and such but various things will be broken, like the Travis configuration. That warning is useful, because the CI configuration in this template assumes GitHub. The release fields are release_date in ISO 8601 format defaulting to today, used in CHANGELOG.rst, year for the copyright year in the Sphinx conf.py, and version, defaulting to 0.1.0, used in .bumpversion.cfg and in the Sphinx conf.py. ## The switches that change what gets generated The remaining fields are switches, and they are where the template earns its keep. Each one adds or removes machinery rather than just filling in a value. c_extension_support controls the C story, and it has three options. "yes" generates a Python C extension, "cffi" generates CFFI bindings against a C library, and "cython" generates a Cython extension. The README notes that enabling it will slightly change the outputted setup.py. A companion switch, c_extension_optional, makes the extensions optional so your package can install even if the extensions cannot be compiled, which is a real consideration for a library that supports a range of platforms. setup_py_uses_setuptools_scm enables setuptools-scm, which derives the version from your VCS tags rather than from a literal. The README points out that you can continue using bumpversion with this enabled, which is an unusual and useful combination. tests_inside_package collects tests that live inside the package, meaning tests that get installed with the package, while the outside of package tests directory will still exist and be collected. That matters for a library where you want the tests available to downstream users. test_matrix_separate_coverage gives you a separate environment for measuring coverage, and it is indicated if you want to run doctests or collect tests from src with pytest. The reason to want this is that measuring coverage and running doctests in the same environment often produces confusing results, since doctests and unit tests exercise different parts of the same code. command_line_interface adds a bin/executable file, with three levels of effort. plain is a very simple command, argparse is a command implemented with argparse, and click is a command implemented with click. The default is plain. One caveat the README flags applies to all of them. If you answer no on the first one then the rest will not have any effect, so just ignore them, and maybe in the future cookiecutter will allow option hiding or something like a wizard. That is a fair description of how a form-based generator behaves, and it means the field list is worth reading once before you answer it. ## The repository layout, and how the generated project is structured The repository itself is small, which is what you expect from a template. The top level holds cookiecutter.json, the file that defines the fields and the defaults, the hooks/ directory for Cookiecutter hooks, pylibrary.py, the script that does the actual generation work, a CHANGELOG.rst, a CONTRIBUTING.rst, a README.rst, the LICENSE, and a directory whose name is a Jinja expression, {{cookiecutter.repo_name}}, which holds the template for the generated project. That layout is the standard Cookiecutter arrangement. The templated directory name is the giveaway, because the template is rendered into a directory named after the answer to repo_name, so a project generated with repo_name set to python-nameless produces a python-nameless directory. The template directory contains the project skeleton that gets rendered, and the hooks handle the steps that have to happen around the rendering rather than inside it, such as creating directories whose names depend on the answers or running a command after the files are written. The repository also carries a LICENSE, and the project is BSD 2-Clause. The release tags are v1.16, v2.0 and v3.0, all dated 2022-11-10, which is worth noting alongside the last push on 2026-04-08. The template itself has not been re-cut since 2022, and the maintenance since then has been to the repository rather than to a new release of the template. The last push date matters for a different reason. The template still targets Python 2.7 and 3.7 in the tox environments and lists Pytest or Nose, Travis-CI and AppVeyor as the CI options, and it builds on setup.py. That is a coherent 2014-to-2022 world, and it is a world that has moved on. Generated projects will need edits before they match a current Python packaging setup, and the Travis-CI configuration will be dead weight in a new project. ## Conclusion cookiecutter-pylibrary suits someone starting a Python library who wants the packaging, testing and documentation plumbing already solved, since the template was written in response to a series of packaging pitfalls posts and includes a check environment that catches a broken README.rst or MANIFEST.in. It is the wrong choice for a web application, since the README points at django-docker for that case, and it is the wrong choice if you want a modern packaging setup, because the template is built around setup.py and bumpversion rather than a pyproject-only build, which reflects a 2022 vintage template. Before using it, read the field list carefully, because answering no to one question silently disables the ones that depend on it, and check the last push on 2026-04-08 against the release tags, where v3.0 dates from 2022-11-10. ## FAQ ### How do I generate a project from cookiecutter-pylibrary? Install the two requirements with pip install tox cookiecutter, then run cookiecutter gh:ionelmc/cookiecutter-pylibrary and answer the field prompts. The README also links python-nameless as a bare library built from the same template if you want to see the result first. ### What does the generated project include? A choice of licenses, tox environments for test management, Pytest or Nose, optional test matrix generation, Travis-CI and AppVeyor configuration, Coveralls or Codecov coverage tracking, Sphinx documentation ready for ReadTheDocs, isort and bumpversion configuration, optional C extension support, and a tox check environment that validates README.rst and MANIFEST.in. ### What is the difference between package_name, distribution_name and module_name? package_name is the name you would import, distribution_name is the name you would pip install, and module_name is the implementation module inside the package, defaulting to core. The README notes that the template assumes there will be an implementation module inside your package. ### Does the template support C extensions? Yes. The c_extension_support field has three options, yes for a Python C extension, cffi for CFFI bindings against a C library, and cython for a Cython extension. A separate c_extension_optional switch lets the package install even if the extensions cannot be compiled, and coverage measurement for the C code is included. ### Is cookiecutter-pylibrary suitable for a web application? No. The README is explicit that if you have a web application rather than a library you should look at django-docker. The template is built around packaging and publishing a library, with setup.py, a check environment and ReadTheDocs configuration. ## Sources - [ionelmc/cookiecutter-pylibrary on GitHub](https://github.com/ionelmc/cookiecutter-pylibrary) - [Issues](https://github.com/ionelmc/cookiecutter-pylibrary/issues) - [License: BSD-2-Clause](https://github.com/ionelmc/cookiecutter-pylibrary/blob/master/LICENSE) - [README](https://github.com/ionelmc/cookiecutter-pylibrary/blob/master/README.md) - [Releases](https://github.com/ionelmc/cookiecutter-pylibrary/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ionelmc-cookiecutter-pylibrary