A Copier template for Python projects built with uv, Ruff, mypy, pytest, a Makefile, and a full Claude Code setup.
Status: early
One command gives you a project that already lints, type-checks and tests on three operating
systems, with Claude Code set up to follow the same rules. Later template improvements reach the
project with uvx copier update.
uvx copier copy gh:jvitorcosta/python-uv-claude-template my-projectI wanted every new project to start with the same lint, type checks, tests, CI and Claude Code rules, and to pull later improvements in without copy-pasting. I use it for my own repos, for example fraud-alert-explainer.
You need uv, Git ≥ 2.31 (pre-commit 4 requires it) and make. uv installs Python for you, so you don't need a system Python. Optional: gh (GitHub CLI) and Claude Code.
| Tool | macOS | Linux (Debian/Ubuntu) | Windows (PowerShell) |
|---|---|---|---|
| uv | brew install uv |
curl -LsSf https://astral.sh/uv/install.sh | sh |
winget install astral-sh.uv |
| Git | brew install git |
sudo apt install git |
winget install Git.Git |
| make | xcode-select --install |
sudo apt install make |
winget install ezwinports.make |
| gh | brew install gh |
cli.github.com | winget install GitHub.cli |
Check: uv --version && git --version && make --version. Restart the terminal after
installing on Windows so PATH picks them up.
On Windows, read the Windows notes once (long paths, make, Git Bash).
uvx copier copy gh:jvitorcosta/python-uv-claude-template my-project
cd my-project
git init -b main
make install
make checkWorks the same in bash, zsh, PowerShell and cmd. You'll be asked for the project name, package name, Python version, whether to include a Typer CLI, and a license, plus three options that are off by default:
| Question | Default | What it changes |
|---|---|---|
include_example |
yes | No: drop the example hello() function and its tests (and the CLI's greet), keeping only __version__. |
include_data_science |
no | Yes: numpy, pandas and scikit-learn; pandas-stubs and a mypy override for scikit-learn so strict still passes; notebooks/ (not linted); data/ and artifacts/ gitignored; brew install libomp on macOS CI for LightGBM/XGBoost wheels. |
protect_project_files |
no | Yes: copier update leaves README.md, CHANGELOG.md and the package __init__.py alone once they exist, instead of merging template changes into files the project has rewritten. |
With the defaults, a generated project is identical to the previous template version.
Existing projects can opt in on their next update, e.g. uvx copier update -d protect_project_files=true.
cd my-project
uvx copier updateCopier reads .copier-answers.yml, re-renders the template at the new version, and
3-way-merges your changes. This is the main reason to use Copier over Cookiecutter.
Commit or stash your work first (Copier refuses to update a dirty repo). It only sees
tagged template versions, so see Releasing.
| Area | Choice |
|---|---|
| Packaging | uv, uv_build backend, src/ layout, uv.lock |
| Lint / format | Ruff (pycodestyle, pyflakes, isort, bugbear, pyupgrade, bandit…) |
| Types | mypy strict, py.typed |
| Tests | pytest + pytest-cov (80% gate) |
| Tasks | Makefile (make help) |
| Git hooks | pre-commit: ruff, mypy, uv lock check, hygiene hooks |
| CI | GitHub Actions on Ubuntu, macOS, Windows (astral-sh/setup-uv) |
| Deps updates | Dependabot (uv + Actions) |
| Docs | README, CONTRIBUTING, CHANGELOG, PR + issue templates |
| Optional | Typer CLI, MIT license, data/ML setup, protected project files |
my-project/
├── src/my_project/ # your package (py.typed); cli.py if you chose the Typer CLI
├── tests/ # pytest, 80% coverage gate
├── notebooks/ # only with include_data_science (data/, artifacts/ gitignored)
├── pyproject.toml # uv_build, ruff, mypy strict, pytest, coverage
├── uv.lock
├── Makefile # make help: install, check, test, format, build, ...
├── .pre-commit-config.yaml
├── .github/ # CI on 3 OSes, Dependabot, PR and issue templates
├── CLAUDE.md, .claude/ # Claude Code setup (below)
├── README.md, CONTRIBUTING.md, CHANGELOG.md
└── .copier-answers.yml # what `copier update` needs
CLAUDE.md # project context, commands, conventions (imports rules)
.mcp.json # team MCP servers (empty to start)
.claude/
├── settings.json # permission allow/ask/deny + hooks
├── rules/ # path-scoped: code-style, testing, api-conventions
├── commands/ # /review, /fix-issue <n>
├── skills/release/ # SKILL.md + changelog-format.md
├── agents/ # code-reviewer, security-auditor
└── hooks/
├── validate_bash.py # PreToolUse: blocks pip, rm -rf /, force-push, push to main, .env reads…
└── format_python.py # PostToolUse: ruff fix + format on each .py edited in the project
The hooks are stdlib Python run with uv run --no-project, so they work on
Windows, macOS and Linux without jq or POSIX tools. validate_bash.py checks each part of a
command line on its own (git push origin fix && gh pr create --base main is fine) and reads the
push's refspecs, so git push origin HEAD:main is caught. format_python.py leaves files outside
the project alone. Both are tested in this repo (make test-hooks). CLAUDE.local.md and
.claude/settings.local.json are gitignored for personal overrides.
See CONTRIBUTING.md. TL;DR: make test tests the hooks, renders the
template four times (default, CLI, bare CLI without the example, data/ML with protected files)
and runs the full check suite on each. CI runs it on
Ubuntu, macOS and Windows (Git Bash and plain cmd).
make test # must pass
# add the version's section to CHANGELOG.md
git commit -am "feat: ..." # Conventional Commits
git tag -a vX.Y.Z -m "vX.Y.Z" # annotated; semver: major = breaking change for generated projects
git push --follow-tags # only pushes annotated tags, hence -aThen in any generated project: uvx copier update.
MIT, see LICENSE. Projects you generate get their own license; the template asks which one you want.