Skip to content

Poetry Template

A comprehensive template for quickly starting new Python projects with modern development tools and best practices.

Python Boilerplate uv Docker License GitHub Actions Status GitHub Actions Status

🚀 Features

  • Python 3.10+
  • uv — Ultra-fast Python package installer and dependency resolver
  • Docker Support — Multi-stage Dockerfiles for both local development and clean production containers
  • GitHub Actions CI/CD — Automated pipelines for code quality checks, testing, security scanning, and Python compatibility validation
  • Dev Containers — Pre-configured development environment for codespaces or remote development
  • Code Quality Tools — Integrated linting and formatting with Ruff, static type checking with MyPy, comprehensive testing with Pytest and checking minimal Python version to run your code (without dependencies) with Vermin
  • Pre-commit Hooks — Automated code quality enforcement (linting, formatting, and tests before every commit)
  • Commitizen — Standardized commit messages and automated changelog/versioning
  • Environment Management — Stage-based configuration system supporting development and production environments
  • MkDocs Documentation — Documentation with Material theme and automated generation
  • Makefile Automation — Simplified command interface for common development tasks

📋 Requirements

  • Python 3.10+
  • uv package manager
  • Docker (optional, for containerized development)
  • Git

⚠️ Important

!

This is a boilerplate template. After cloning or generating your project, remember to:

  • Update your project name in pyproject.toml and docker-compose.yml
  • Replace this README with documentation specific to your project
  • Configure environment variables in .env.development and .env.production
  • Customize the Makefile commands as needed for your project

⚡ Quick Start

Step 1: Clone the repository

git clone https://github.com/python-boilerplate/uv-template
cd uv-template

Step 2: Initialize the project

make init
This will install dependencies (with creating virtual environment) and set up pre-commit hooks

Step 3: Set up environment variables

cp example.env .env.development
# Edit .env.development as needed

Step 4: Run the application

make run