• Copier-powered scaffolding: Effortlessly generate or update projects with one command.

• Task runner integration: Project tasks are organized using duty and exposed via a Makefile for easy command-line usage. Simply run tasks with make <task> (e.g. make check, make docs).

• Quality & standards

  • Formatting and Linting: Ruff ➜ make format & make check-quality
  • Type checking: Mypy ➜ make check-types
  • Pre-commit hooks: pre-commit

• Testing & coverage

  • pytest ➜ make test
  • Coverage (text, HTML, XML) ➜ make coverage
  • Compatibility testing for multiple versions of Python with Tox and its plugin tox-uv ➜ make tox

• Documentation

  • MkDocs with mkdocs-material theme
  • Live server: make docs (serves on localhost:8080)
  • Deploy to GitHub Pages: make docs-deploy

• Release & changelog

  • Conventional Commits + Commitizen + gitmoji
  • Automated CHANGELOG.md updates
  • Release new versions ➜ make release

• Docker & Docker Compose

  • Generate Dockerfile + compose.yml for local development and deployment (GPU support)
  • Docker targets: make docker-build, make docker-start, make docker-stop

• Optional tooling

  • Typer CLI scaffold
  • Strict typing
  • Run tests with parallel execution via pytest-xdist
  • Preconfigured dependency categories (ML, data, web, etc.)

• CI/CD Workflows

  This template includes GitHub Actions workflows for continuous integration, testing, and release automation:

  • PR Commenting (pr-thank-you.yaml): Posts a fun GIPHY comment on new pull requests using docker-action-pr-giphy-comment

  • CI/CD Pipeline (main.yaml.jinja):

    • Checks: Linting (Ruff), type checking (Mypy), documentation build.
    • Tests: Runs pytest across supported Python versions using a matrix strategy.
    • Releases: Automatically publishes releases when a Git tag is pushed.
    • Docs Deployment: Deploys MkDocs documentation to GitHub Pages.
    • Package Publishing (optional): Publishes the package to PyPI if publish_to_pypi is enabled and PYPI_TOKEN is set.

  These workflows are generated into .github/workflows/ in the scaffolded project. You can customize them further as needed.

• Python ≥ 3.10
• Copier ≥ 9.10.2
• copier-templates-extensions ≥ 0.3.2
• uv (if not installed check uv installation guide)

# 1. Scaffold a new project # Option 1: Use uvx to run Copier with extensions uvx --with copier-templates-extensions copier copy --trust gh:bassemkaroui/python-template-uv /path/to/my-project # Option 2: Install Copier globally uv tool install copier --with copier-templates-extensions # Then run copier copy --trust gh:bassemkaroui/python-template-uv /path/to/my-project # Notes: # • copier.yaml automatically runs `git init`, so `--trust` is required # • Add `--prereleases` to include pre-release versions # • Add `--vcs-ref=HEAD` to use the latest commit # 2. Enter your project cd /path/to/my-project # 3. Set up development environment and hooks make setup-dev # 4. (Optional) Install your CLI globally via uv make setup-cli # 5. Run quality & tests make check # runs all checks: lint, types, docs build, API, etc.

Stay up to date

cd /path/to/my-project uvx copier update --trust --exclude src/ --exclude tests/ .

All tasks are defined in duties.py and exposed through make. Common duties include:

build Build source and wheel distributions. check Check it all! check-api Check for API breaking changes. check-docs Check if the documentation builds correctly. check-quality Run linters and format checks. check-types Run static type checks. clean Delete build artifacts. clean-cache Remove cache files. coverage Generate coverage reports (text, HTML, XML). docker-build Build Docker images. docker-exec-* Dockerized executions of checks, tests, docs, coverage. docker-start Start Docker Compose services. docker-stop Stop and remove Docker Compose services. docs Serve the documentation (localhost:8080). docs-deploy Publish docs to GitHub Pages. format Auto-format code (Ruff). publish Upload distributions to PyPI. release Automate version bump, changelog, and publish. setup Bootstrap prod environment. setup-cli Install the project's CLI globally via uv. setup-dev Bootstrap dev environment & install pre-commit hooks. test Run tests with pytest. tox Run tests across multiple Python versions. 

For the full list and details, see duties.py.

When running copier, you’ll be prompted for:

See the full list in copier.yaml.

This project is released under the MIT License. See LICENSE for details.