A batteries-included Cookiecutter template for modern Python packages — with uv, Ruff, pre-commit, CI, and Dependabot baked in.
- Package management — uv for fast, reliable dependency resolution
- Task runner — Poe the Poet for simple, cross-platform task definitions
- Linting & formatting — Ruff with a curated set of lint rules
- Git hooks — pre-commit with hooks for linting, formatting, and more
- CI — GitHub Actions workflow for tests, linting, and hook checks out of the box
- Dependency updates — Dependabot configuration with auto-merge support
- pyenv for Python version management
- uv for package management
- Poe the Poet for task running
- pre-commit for git hooks
- cookiecutter for generating packages from this template
cookiecutter gh:mt-krainski/matts-python-package-templateYou'll be prompted for a few details:
project_name [...]: My Awesome Package
author [...]: Your Name
email [...]: you@example.com
use_jupyter [y]: n
Then set up your development environment:
cd my-awesome-package
poe configureThis installs dependencies, sets up pre-commit hooks, and creates a .env file.
Verify everything works:
poe lint
poe test| Task | Description |
|---|---|
poe configure |
Set up the development environment (install deps, pre-commit hooks, .env file) |
poe update |
Update dependencies and pre-commit hooks |
poe lint |
Run Ruff linting and format checks |
poe test |
Run tests with coverage and display the coverage report |
poe hooks-run |
Run all pre-commit hooks against the repo |
poe hooks-update |
Update pre-commit hooks to latest versions |
Run poe with no arguments for a full list of available tasks.
Every push or PR to main runs:
- Tests (
poe test-full) - Linting (
poe lint) - Pre-commit hooks (
poe hooks-run)
This template is opinionated — it picks modern, fast tooling and prioritizes a single-tool-per-job approach.
- uv — Written in Rust, blazing fast, and consolidates package management, virtualenv creation, and Python version management into a single binary. Quickly becoming the de facto standard for modern Python projects.
- Ruff — A single tool for both linting and formatting, with 800+ built-in rules that run in under a second. Adopted by FastAPI, Pandas, Airflow, and many others.
- Poe the Poet — Tasks defined directly in
pyproject.toml, automatic virtual environment integration, and support for sequences, arguments, and shell completion. Think npm scripts, but for Python.
The template repo CI also regenerates example-package/ from the template and verifies the result matches what's committed. This catches any drift between the template and its example output.
To enable Dependabot auto-merge on a generated package, you need two changes in your GitHub repository settings:
- Create a Ruleset for the
mainbranch. Enable "Require status checks to pass" with at least thetestcheck. - Enable "Allow auto-merge" under General settings.
This template includes an automated system that keeps package versions in sync between the example-package/ directory and the template files. Here's how it works:
- Dependabot creates PRs to update dependencies in
example-package/ - Sync workflow automatically runs on Dependabot PRs (when opened, synchronized, or reopened)
- Version sync script (
poe sync-versions) updates the dependencies in the template package - Changes are committed directly to the Dependabot PR with a summary comment
You can manually sync versions at any time:
poe sync-versionsThis will sync versions from example-package/ to the template directory and update the lockfile.
Contributions are welcome — feel free to open an issue or submit a PR.
This project is licensed under the MIT License.