Python Copier Template

A simple modern Python project template powered by Copier.

Article日本語記事

Features

• 🚀 Modern Python: Support for Python 3.10-3.14
• 📦 uv Package Manager: Fast and reliable package management with uv
• 🐳 Docker Support: Complete Docker development environment
• 📦 Devcontainer Support: VS Code devcontainer for consistent development
• ✨ AI Editor Support: AGENTS.md and CLAUDE.md included for AI-powered development
• 📝 Type Hints: Full type annotation support with modern Python features
• 🔎 Type Checking: Pre-configured ty for static type checking
• 🔍 Code Quality: Pre-configured Ruff for linting and formatting
• 🧪 Testing: pytest setup with example tests
• 🔧 Pre-commit Hooks: Automated code quality checks
• 🏗️ CI Ready: GitHub Actions workflows included

Quick Start

Pre-Requirements

• uv: Fast Python package installer

Generate a New Project

uvx copier copy gh:mjun0812/python-copier-template your-project-name

Follow the interactive prompts to configure your project:

• Project name: Your project's name
• Python version: Choose from 3.10, 3.11, 3.12, 3.13, or 3.14
• Package name: The name used for importing your package (e.g., import package_name)
• Description: A short description of your project
• Author name: Your name
• Author email: Your email address

Development Setup

After generating your project:

cd your-project-name
# Install dependencies
uv sync
# Install pre-commit hooks
uv run pre-commit install
# Run tests
uv run pytest
# Run formatting and linting (automatically runs on commit)
uv run ruff format .
uv run ruff check .# Run type checking
uv run --frozen ty check
# Auto Fix
uv run ruff check . --fix

Docker Development Setup

The template includes a complete Docker setup:

# create uv.lock file
uv sync
# use the provided scripts
./docker/build.sh
./docker/run.sh # or./docker/run.sh (Command)# Build and run with Docker Compose
docker compose build
docker compose up

VS Code Devcontainer

Open the project in VS Code and use the "Reopen in Container" command for a fully configured development environment. Devcontainer will automatically install uv, Claude Code, and pre-commit hooks. The image build installs the latest Codex release, so rebuilding the image updates Codex.

The container mounts the host ${HOME}/.claude and ${HOME}/.codex directories at /home/vscode/.claude and /home/vscode/.codex for authentication. These bind mounts are read-write, so changes made in the container can affect the host configuration. The uv cache is kept in a named volume and reused across container rebuilds.

Update Template

cd your-project-name
uvx copier update -A

Project Structure

your-project/
├── src/
│ └── your_project/ # Main package
├── tests/ # Test files
├── docker/ # Docker configuration
├── compose.yml # Docker Compose setup
├── pyproject.toml # Project configuration
└── README.md # Project documentation

AI Editor Support

• AGENTS.md(./template/AGENTS.md)
• CLAUDE.md(./template/CLAUDE.md)

Q&A

How do I run type checking?

Run the pre-configured ty type checker:

uv run --frozen ty check

Support

• 📖 Copier Documentation
• 🐍 uv Documentation
• 🔍 Ruff Documentation