¶

A library and CLI app for rendering project templates.

• Works withlocal paths andGit URLs.
• Your project can include any file and Copier can dynamically replace values in any kind of text file.
• It generates a beautiful output and takes care of not overwriting existing files unless instructed to do so.

Installation¶

1. Install Python 3.10 or newer.
2. Install Git 2.27 or newer.
3. To use as a CLI app:pipx install copier oruv tool install copier
4. To use as a library:pip install copier orconda install -c conda-forge copier

Homebrew formula¶

To install the latest Copier release usingits Homebrew formula for macOS or Linux:

brewinstallcopier

Quick start¶

To create a template:

📁my_copier_template# your template project├──📄copier.yml# your template configuration├──📁.git/# your template is a Git repository├──📁{{project_name}}# a folder with a templated name│└──📄{{module_name}}.py.jinja# a file with a templated name└──📄{{_copier_conf.answers_file}}.jinja# answers are recorded here

Content of thecopier.yml file:

# questionsproject_name:type:strhelp:What is your project name?module_name:type:strhelp:What is your Python module name?

Content of the{{project_name}}/{{module_name}}.py.jinja file:

print("Hello from {{module_name}}!")

Content of the{{_copier_conf.answers_file}}.jinja file:

# Changes here will be overwritten by Copier{{_copier_answers|to_nice_yaml -}}

To generate a project from the template:

• On the command-line:

  copiercopypath/to/project/templatepath/to/destination

• Or in Python code, programmatically:

  fromcopierimportrun_copy# Create a project from a local pathrun_copy("path/to/project/template","path/to/destination")# Or from a Git URL.run_copy("https://github.com/copier-org/copier.git","path/to/destination")# You can also use "gh:" as a shortcut of "https://github.com/"run_copy("gh:copier-org/copier.git","path/to/destination")# Or "gl:" as a shortcut of "https://gitlab.com/"run_copy("gl:copier-org/copier.git","path/to/destination")

Basic concepts¶

Copier is composed of these main concepts:

1. Templates. They lay out how to generate the subproject.
2. Questionnaires. They are configured in the template. Answers are used to generate projects.
3. Projects. This is where your real program lives. But it is usually generated and/or updated from a template.

Copier targets these main human audiences:

1. Template creators. Programmers that repeat code too much and prefer a tool to do it for them.

   Tip: Copier doesn't replace the DRY principle... but sometimes you simplycan't be DRY and you need a DRYing machine...

2. Template consumers. Programmers that want to start a new project quickly, or that want to evolve it comfortably.

Non-humans should be happy also by using Copier's CLI or API, as long as theirexpectations are the same as for those humans... and as long as they have feelings.

Templates have these goals:

1. Code scaffolding. Help consumers have a working source code tree as quickly as possible. All templates allow scaffolding.
2. Code lifecycle management. When the template evolves, let consumers update their projects. Not all templates allow updating.

Copier tries to have a smooth learning curve that lets you create simple templates thatcan evolve into complex ones as needed.

Browse or tag public templates¶

You can browse public Copier templates on GitHub usingthecopier-template topic. Use them asinspiration!

If you want your template to appear in that list, just add the topic to it! 🏷

Show your support¶

If you're using Copier, consider adding the Copier badge to your project'sREADME.md:

[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)

...orREADME.rst:

..image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json:target: https://github.com/copier-org/copier:alt: Copier

...or, as HTML:

<ahref="https://github.com/copier-org/copier"><imgsrc="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json"alt="Copier"style="max-width:100%;"/></a>

Copier badge variations¶

1. Badge Grayscale Border

2. Badge Grayscale Inverted Border

3. Badge Grayscale Inverted Border Orange

4. Badge Grayscale Inverted Border Red

5. Badge Grayscale Inverted Border Teal

6. Badge Grayscale Inverted Border Purple

7. Badge Black

Credits¶

Special thanks go tojpsca for originally creatingCopier.This project would not be a thing without him.

Many thanks topykong who took over maintainership on theproject, promoted it, and laid out the bases of what the project is today.

Big thanks also go toyajo for his relentless zest forimprovingCopier even further.

Thanks a lot,pawamoy for polishing very important roughedges and improving the documentation and UX a lot.

Also special thanks tosisp for being very helpful inpolishing documentation, fixing bugs, helping the community and cleaning up thecodebase.

And thanks to all financial supporters and folks that give us a shiny star! ⭐