!Copier
A library and CLI app for rendering project templates.
- Works with local paths and Git URLs.
- Your project can include any file and Copier can dynamically replace values in any
- It generates a beautiful output and takes care of not overwriting existing files
Installation
- Install Python 3.11 or newer.
- Install Git 2.27 or newer.
- To use as a CLI app:
pipx install copieror
uv tool install copier
- To use as a library:
pip install copierorconda install -c conda-forge copier
Homebrew formula
To install the latest Copier release using its Homebrew formula for macOS or Linux:
brew install copier
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 the copier.yml file:
``yaml title="copier.yml"
questions
project_name:
type: str
help: What is your project name?
module_name: type: str help: What is your Python module name?
python+jinja title="{{project_name}}/{{module_name}}.py.jinja" print("Hello from {{module_name}}!")Content of the{{project_name}}/{{module_name}}.py.jinjafile:
yaml+jinja title="{{_copier_conf.answers_file}}.jinja"Content of the{{_copier_conf.answers_file}}.jinjafile:
Changes here will be overwritten by Copier
{{ _copier_answers|to_nice_yaml -}}To generate a project from the template:
- On the command-line:
shell copier copy path/to/project/template path/to/destination
- Or in Python code, programmatically:python
from copier import run_copy
# Create a project from a local path run_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")
md## Basic conceptscopier-templateCopier is composed of these main concepts:
projects.
- Templates. They lay out how to generate the subproject.
- Questionnaires. They are configured in the template. Answers are used to generate
and/or updated from a template.
- Projects. This is where your real program lives. But it is usually generated
Copier targets these main human audiences:
it for them.
- Template creators. Programmers that repeat code too much and prefer a tool to do
_Tip:_ Copier doesn't replace the DRY principle... but sometimes you simply can't be DRY and you need a DRYing machine...
that want to evolve it comfortably.
- Template consumers. Programmers that want to start a new project quickly, or
Non-humans should be happy also by using Copier's CLI or API, as long as their expectations are the same as for those humans... and as long as they have feelings.
Templates have these goals:
consumers have a working source code tree as quickly as possible. All templates allow scaffolding.
- Code scaffolding>). Help
projects. Not all templates allow updating.
- Code lifecycle management. When the template evolves, let consumers update their
Copier tries to have a smooth learning curve that lets you create simple templates that can evolve into complex ones as needed.
Browse or tag public templates
You can browse public Copier templates on GitHub using the
topic. Use them as inspiration!README.mdIf 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's
:
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...orREADME.rst:
...or, as HTML:html
Copier badge variations
- Badge Grayscale Border
- Badge Grayscale Inverted Border
- Badge Grayscale Inverted Border Orange
- Badge Grayscale Inverted Border Red
- Badge Grayscale Inverted Border Teal
- Badge Grayscale Inverted Border Purple
- Badge Black
Credits
Special thanks go to jpsca for originally creating
Copier.
This project would not be a thing without him.
Many thanks to pykong who took over maintainership on the
project, promoted it, and laid out the bases of what the project is today.
Big thanks also go to yajo for his relentless zest for
improving
Copier` even further.
Thanks a lot, pawamoy for polishing very important rough edges and improving the documentation and UX a lot.
Also special thanks to sisp for being very helpful in polishing documentation, fixing bugs, helping the community and cleaning up the codebase.
And thanks to all financial supporters and folks that give us a shiny star! ⭐