Cookiecutter PyPackage GitLab

Cookiecutter template for a Python package in the GitLab CI/CD ecosystem.

Project links

• PyPI: https://pypi.org/project/cookiecutter-pypackage-gitlab/
• Documentation: https://sck.gitlab.io/cookiecutter-pypackage-gitlab/
• Source & issues: https://gitlab.com/sck/cookiecutter-pypackage-gitlab

Features

• Dependency management with uv
• Task running with make
• Testing with pytest under GitLab CI
• Auto-publish to a package registry when you push a v* tag. (For PyPI no API tokens are needed by using Trusted Publishers.)
• Hardened GitLab CI workflows: version-pinned Docker images
• Documentation site built with Zensical and auto-deployed to GitLab Pages.
• Linting with ruff, type checking with mypy and ty
• Command line interface using argparse

Quickstart

Generate a new Python package by creating a temporary venv, installing the package, and running the command.

python -m venv venv
source venv/bin/activate
pip install cookiecutter-pypackage-gitlab
cookiecutter-pypackage-gitlab

If you have uvx installed, you can also use it to run cookiecutter-pypackage-gitlab without explicitly creating a temporary venv, installing the package, running the package, and then removing the temporary venv:

uvx cookiecutter-pypackage-gitlab

You'll be prompted for your project's values (name, description, author details, GitLab repository URL, publish registry, and so on). See docs/prompts.md for the full list and what each value controls.

Then:

• Review src/ and tests/; see tutorial Step 7 for what to adapt or delete.
• Create a GitLab repo and push your code
• Enable GitLab Pages: Settings > Pages > Source: GitLab CI
• Set up your selected package registry (see Registry setup -- covers GitLab Package Registry, PyPI Trusted Publishing, and TestPyPI for dry runs).
• Release your package: see Release checklist for the workflow.

See the full documentation for the tutorial, CI/CD reference, design notes, and more.

Development

To set up for local development:

git clone git@gitlab.com:sck/cookiecutter-pypackage-gitlab.git
cd cookiecutter-pypackage-gitlab
make venv
source venv/bin/activate
make init
make sync-devci

Activating the venv is optional — every make target and the pre-commit git hook use ./venv directly. Activate it when you want ruff, pytest, and friends on your PATH.

Run quality checks (format, lint, type check, test):

make qa

Watch the template for changes and auto-regenerate python-boilerplate/ in the repo root (useful when iterating on template files):

make template-watch

Release cycle

See Release checklist for the full recurring workflow: preparing HISTORY.md, setting the version, tagging, and publishing to PyPI.

Not exactly what you want?

Don't worry, you have options:

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.

Similar Cookiecutter templates

This cookiecutter template was based on the v0.4.0 (2026-02-16) release of Cookiecutter PyPackage (a GitHub-centric template). That package lists other forks you can explore to get ideas at network and family tree.

Or submit a merge request

I also accept merge requests on this, if they're small, atomic, follow my design decisions, and if they make my own packaging experience better.

License

MIT.