Skip to content

How to Update from Template

This guide shows you how to pull in the latest template improvements to an existing project generated from python-package-copier.

Prerequisites

  • A project previously generated with uvx copier copy gh:stateful-y/python-package-copier
  • The project must contain a .copier-answers.yml file (generated automatically)
  • copier installed (uvx copier works)

Check Your Current Template Version

cat .copier-answers.yml

The _commit field shows the template commit your project was generated from.

Update to Latest Template

Run from your project's root directory:

copier update --trust

Copier will:

  1. Pull the latest template from gh:stateful-y/python-package-copier
  2. Show you a diff of changes
  3. Prompt for any new configuration questions added since your last update
  4. Apply updates while preserving your modifications

Update to a Specific Version

Pin to a specific template version:

copier update --trust --vcs-ref=v1.2.0

Or update to a specific commit:

copier update --trust --vcs-ref=abc123

Handle Conflicts

If you've modified files that the template also changed, Copier will flag conflicts.

Inline Conflict Markers (Default)

copier update --trust --conflict inline

This adds Git-style conflict markers in the affected files:

<<<<<<< before updating
your local changes
=======
template changes
>>>>>>> after updating

Resolve them manually, then commit.

Reject Files

copier update --trust --conflict rej

This creates .rej files alongside conflicting files. Review each .rej file, apply the changes you want, and delete the .rej files.

What Gets Updated

Template updates can include:

  • CI workflow improvements - new testing strategies, updated actions versions
  • Tool configuration - ruff rules, coverage settings, pre-commit hooks
  • Documentation scaffolding - new doc pages, improved templates
  • Build system - dependency group changes, hatchling config

What Is Preserved

Copier respects your local changes. Files you've customized are merged, not overwritten. Specifically:

  • Your source code in src/ is never touched by template updates
  • Your test files in tests/ are preserved
  • Custom content you added to documentation is preserved
  • Dependencies you added to pyproject.toml are preserved

AI-Assisted Updates

If you use GitHub Copilot or a similar AI coding assistant, you can ask it to handle the update for you. The template ships with an update-from-template skill that automates the full workflow:

  1. Pre-flight checks (clean working tree, current template version)
  2. Detecting which files you've customized vs. kept as-is
  3. Running copier update on a dedicated branch
  4. Resolving conflicts using a 3-tier file classification (template-managed, merge-required, local-owned)
  5. Verifying tests and linting pass after the update

To trigger it, ask your AI assistant: "update from template" or "sync template changes" from within your generated project.

Troubleshooting

Problem: copier update fails with "not a copier project" : Ensure .copier-answers.yml exists in the project root. If it was accidentally deleted, you cannot update - you would need to regenerate the project.

Problem: Too many conflicts after a long gap : Update incrementally by specifying intermediate versions with --vcs-ref.

Problem: New template variables have no answers : Copier will prompt you for any new variables interactively. To set defaults non-interactively, use --defaults.

See Also