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, plus shared Claude Code / Codex hooks that format and lint Python files as the agent edits them
• 📝 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
• 🔧 Git Hooks: Automated code quality checks on commit with prek
• 🏗️ 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
• License: MIT, Apache-2.0, BSD-3-Clause, or None (no LICENSE file)

Development Setup

After generating your project:

cd your-project-name

# Install dependencies
uv sync

# Install git hooks
uv run prek install

# Run the application
uv run your-project-name

# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov

# 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, Codex, and git hooks. The image build installs the latest Claude Code and Codex releases with their official installers, so rebuilding the image updates both.

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)
• .claude/settings.json: Claude Code permissions (pre-approved uv run --frozen, uv sync, read-only git commands; .env files denied) and a PostToolUse hook
• .codex/hooks.json: the same PostToolUse hook for Codex
• .agents/hooks/format-python.sh: the hook script, runs ruff format and ruff check --fix on the edited file

Both tools apply this configuration only in a trusted project. Claude Code asks once when you open the project; Codex additionally requires reviewing and trusting the hook with /hooks, and silently skips it until then.

Support

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