Skip to content

Copier Modern Python

Copier template for modern Python projects.

This template provides a comprehensive, production-ready Python project structure with modern tooling and best practices. It supports both PDM and uv package managers, includes automated testing and quality checks, comprehensive documentation setup, and CI/CD workflows for multiple Git providers.

Features

During the Copier generation process, you'll be prompted to select your preferences for package management, Git provider, licensing, and other options. The template then generates a customized project structure with only the tools and configurations you need.

Package Management

Choose between two modern Python package managers. PDM offers cutting-edge dependency management with PEP 582 support, allowing you to avoid virtual environments entirely. uv provides blazing-fast package installation and resolution, significantly reducing setup times. Both managers handle dependency locking, virtual environment management, and script execution seamlessly.

Task Runner

Nox replaces traditional Makefiles with Python-based automation. The template includes pre-configured sessions for testing across multiple Python versions, code formatting, quality checks, and documentation building. This ensures consistent development workflows across different environments and team members.

Project layouts

Choose the kind of project you are starting and the generated tree fits it, so nothing has to be deleted before work begins:

Layout What you get Published Container
library (default) An importable src/ package you distribute to others Yes Opt-in
script The same, plus a click command and a console entry point Yes Opt-in
ml A Metaflow flow, a notebooks/ directory executed as part of the test suite and rendered into the docs, and a data/ directory kept out of version control No Opt-in
dataeng A Kedro pipeline with a conf/ catalog, plus data/ kept out of version control No Yes
service A FastAPI application with a health endpoint, served by uvicorn No Yes

A Dockerfile is generated for the layouts that are deployed rather than installed, and can be opted into for any of the others. Kedro ships telemetry as a core dependency, so the dataeng layout writes a .telemetry file declining it — a project generated from a template never had the chance to consent, so consent is not assumed.

Every layout carries the same quality floor: the same task names, the same checks at the same strictness, and the same release topology. Layouts differ in what they generate, never in whether that floor applies. The machine learning layout publishes nothing to a package index, so publishing is simply absent rather than generated and left broken.

Layouts add only what a task actually exercises, and any framework they add runs locally with no account or server to provision. Changing a project's layout after generation is out of scope: the answer can be changed, but the result is whatever the update merge produces, and it is neither supported nor tested.

AI assistants

Generated projects can carry conventions for AI coding agents, asked as two independent options. An AGENTS.md (the agent-agnostic standard that Claude Code, Cursor and others read directly) is seeded from what the project enforces: the task interface with the correct commands for the chosen package manager, the quality floor and the rule not to weaken it, the commit convention, the release topology, and notes for the chosen layout. Separately, an opt-in Spec Kit constitution seeds the project's principles in Spec Kit's format; run specify init alongside it to add the rest of the workflow. The two are distinct — Spec Kit does not read AGENTS.md — so you can take either, both, or neither.

Documentation

Automatic documentation generation using properdocs with the beautiful Material theme. The mkdocstrings plugin extracts API documentation directly from your docstrings, keeping documentation in sync with code. Includes example pages, custom CSS, and responsive design out of the box.

Code Quality & Formatting

Enforce consistent code style with black for uncompromising formatting and docformatter for PEP 257 compliant docstrings. Ruff provides extremely fast linting with hundreds of rules, replacing multiple toolsin a single, performant package. interrogate ensures your code is properly documented by checking docstring coverage.

Security & Safety

Proactive security scanning with pip-audit to detect known vulnerabilities in dependencies and bandit to identify common security issues in your code. Both run as part of the checks task and in CI, and both read their configuration from pyproject.toml, so a project records its own suppressions where the rest of its tooling lives.

Type Checking

mypy provides static type analysis to catch type-related bugs before runtime. The template includes sensible defaults and excludes common directories like tests and generated documentation.

Testing

Comprehensive testing setup with pytest and essential plugins. coverage tracks code coverage with HTML reports. Tests run in parallel for faster feedback during development.

Development Workflow

pre-commit hooks automatically run quality checks before each commit, preventing broken code from entering the repository. git-changelog generates beautiful changelogs from conventional commit messages, automating release documentation.

Releasing has one shape on every provider. The release task is the local half: it writes the changelog, opens and merges the release pull request, and pushes the tag. The pipeline is the only publisher, and it will not publish a tag whose tests and quality checks have not passed. Exactly one publisher exists for a given version, so a local release cannot race the pipeline for it.

Platform Support

Supports all major Git providers with pre-configured CI/CD workflows. Choose from GitHub Actions, GitLab CI, Azure Pipelines, or Bitbucket Pipelines. Includes automated testing, quality checks, documentation deployment, and PyPI publishing. License selection covers all popular open-source licenses with proper SPDX identifiers.

Prerequisites

Before using this template, ensure you have the following tools installed:

Required Tools

Package Manager

Choose one of the following:

  • PDM (>= 2.9.0)
  • uv (>= 0.1.0)

Git Provider CLI Tools

Depending on your chosen Git provider, install the corresponding CLI tool for automated releases:

Usage

Creating a New Project

To create a new Python project using this template:

copier copy "gh:georgedouzas/copier-modern-python.git" /path/to/your/new/project

The template will prompt you for various configuration options including:

  • Project name and description
  • Author information
  • Package manager preference (PDM or uv)
  • Project layout (library, command line tool, machine learning, data engineering, or service)
  • Whether to include a Dockerfile, and conventions for AI coding agents (AGENTS.md, Spec Kit)
  • Git provider (GitHub, GitLab, Azure DevOps, Bitbucket, or None)
  • License selection
  • Python version requirements
  • Publishing preferences, unless the layout publishes nothing

Updating an Existing Project

To update your project with the latest template version:

cd /path/to/your/project
copier update

This will apply any template updates while preserving your project-specific configurations.