Copier Template Extensions

0.3.3 · active · verified Fri Apr 17

Copier Template Extensions (copier-template-extensions) is a specialized Jinja2 extension for Copier, enabling the loading of other Jinja2 extensions using file paths relative to the template root, rather than standard Python dotted paths. As of version 0.3.3, it offers improved migration support. The project maintains an active release cadence with periodic updates.

Common errors

```
ModuleNotFoundError: No module named 'copier_templates_extensions'
```
cause Your `copier.yaml` or Python code still references the old, plural package name (`copier_templates_extensions`) after upgrading to version 0.3.2 or newer.

fix Update all references in `copier.yaml` and Python code from `copier_templates_extensions` to `copier_template_extensions` (singular).
```
Failed to load extension './my_extension.py:my_filter': Could not import 'my_filter' from module 'my_extension' (Jinja2Error)
```
cause The `copier-template-extensions` library itself was not loaded by Copier, so it cannot resolve relative paths for other extensions specified in `_extensions`.

fix Ensure `"copier_template_extensions.CopierExtension"` is explicitly listed as the first item in the `_extensions` key in your `copier.yaml`.
```
Error in extension configuration for 'copier_template_extensions.CopierExtension': The 'copier' library version is too old. (CopierInternalError)
```
cause The installed `copier` version is older than 9.2, which is required by `copier-template-extensions` 0.3.1 and newer.

fix Upgrade your `copier` installation to version 9.2 or newer: `pip install --upgrade copier`.

Warnings

breaking The project name changed from `copier-templates-extensions` (plural) to `copier-template-extensions` (singular) in version 0.3.2.
Fix: Update your `pip install` commands and all references in `copier.yaml` and Python code from `copier_templates_extensions` to `copier_template_extensions`.
breaking Copier Template Extensions now requires `copier>=9.2`.
Fix: Ensure your `copier` installation is updated to version 9.2 or newer (`pip install --upgrade copier`).
gotcha This library enables loading Jinja2 extensions via relative file paths. If you attempt to use a relative path for an extension without first loading `copier_template_extensions.CopierExtension`, Copier will raise a `ModuleNotFoundError` or `TemplateSyntaxError`.
Fix: Always include `"copier_template_extensions.CopierExtension"` in the `_extensions` list in your `copier.yaml` when you intend to use relative paths for other extensions.

Install

pip install copier-template-extensions Install stable version

Imports

copier_template_extensions.CopierExtension
wrong:
```
copier_templates_extensions.CopierExtension
```
correct:
```
copier_template_extensions.CopierExtension
```
This is the string identifier used in your `copier.yaml` file to enable the extension within Copier. The `wrong` path refers to the old, plural package name before version 0.3.2.

Quickstart

To enable `copier-template-extensions`, include its module path in the `_extensions` list within your `copier.yaml`. This allows Copier to load other Jinja2 extensions specified by relative file paths within your template, such as `my_template_utils.py` shown here. The example demonstrates a custom filter named `custom_filter`.

# copier.yaml
_extensions:
  - "copier_template_extensions.CopierExtension"
  # You can now load other extensions using relative paths:
  - "./my_template_utils.py:custom_filter"

# my_template_utils.py
def custom_filter(value):
    return f"CUSTOM({value.upper()})"

# template.txt.jinja
Hello {{ 'world' | custom_filter }}

view raw JSON →