Copier

Warnings

• breaking Copier 9.x and newer requires Python 3.10 or higher. Older versions supported Python 3.6+.
  Fix: Ensure your environment uses Python 3.10 or a more recent version. Upgrade your Python interpreter if necessary.
• breaking The `_copier_conf.json()` method for accessing configuration data within templates has been removed.
  Fix: Replace all instances of `_copier_conf.json()` in your templates with `_copier_conf|to_json` to correctly render JSON representations of the configuration.
• gotcha When updating a project, Copier handles merge conflicts by default using 'inline' markers, similar to Git merge conflicts. This can leave `<<<<<<<`, `=======`, `>>>>>>>` markers in your files.
  Fix: To generate separate `.rej` files for conflicts instead of inline markers, use the `--conflict rej` option when running `copier update` or `copier recopy`.
• gotcha If your Copier template uses custom Jinja extensions or other Python packages for tasks, these dependencies must be installed in the same Python environment where Copier itself is installed. Copier does not automatically manage template-specific Python dependencies.
  Fix: Manually install any additional Python packages required by your template's custom logic into the environment where Copier is running (e.g., `pip install copier my-template-extension`). Consider using `pipx` for isolated Copier installations and then injecting template-specific dependencies into that `pipx` environment.
• gotcha When writing custom Python code for Copier templates (e.g., post-copy tasks, custom Jinja extensions), be mindful of mutable default arguments in function definitions. Changes to these mutable defaults (e.g., lists, dictionaries) will persist across multiple calls, leading to unexpected behavior.
  Fix: Initialize mutable default arguments to `None` and assign the mutable object inside the function if `None` is passed. Example: `def func(arg=None): arg = arg if arg is not None else []`.

Install

• pip install copier Install with pip

Imports

• run_copy

  from copier import run_copy

  The `copy` function was used in older versions of Copier. As of recent major versions (e.g., Copier 9.x), `run_copy` is the canonical and preferred function for programmatically copying templates, offering explicit parameters instead of `**kwargs`.

Quickstart

This quickstart demonstrates how to programmatically use `copier.run_copy` to generate a new project from a local template. It first creates a minimal template directory with a `copier.yml` and a Jinja2-templated file, then copies it to a destination, providing answers as a dictionary. The generated project's README content is then printed.

import os
import shutil
from pathlib import Path
from copier import run_copy

# Define paths for demonstration
template_path = Path('./my_template')
dest_path = Path('./my_new_project')

# Clean up previous runs for idempotent quickstart
if dest_path.exists():
    shutil.rmtree(dest_path)
if template_path.exists():
    shutil.rmtree(template_path)

# 1. Create a dummy template structure
template_path.mkdir(exist_ok=True)
(template_path / 'copier.yml').write_text(
    """
    # questions
    project_name: 
      type: str
      help: What is your project name?
    author_name:
      type: str
      default: 'John Doe'
    """
)
(template_path / '{{ project_name }}').mkdir()
(template_path / '{{ project_name }}' / 'README.md.jinja').write_text(
    """
    # {{ project_name }}

    This project was generated by {{ author_name }}.
    """
)

print(f"Template created at: {template_path.resolve()}")

# 2. Programmatically copy the template
# In a real scenario, these answers might be interactively prompted or passed via CLI
answers = {
    'project_name': 'MyAwesomeProject',
    'author_name': 'AI Assistant'
}

run_copy(
    str(template_path),
    str(dest_path),
    data=answers,
    overwrite=True # Use with caution in real projects
)

print(f"Project generated at: {dest_path.resolve()}")
print("Generated README.md content:")
print((dest_path / 'MyAwesomeProject' / 'README.md').read_text())

# Clean up after quickstart
shutil.rmtree(template_path)
shutil.rmtree(dest_path)