Skip to content
Library and command-line utility for rendering projects templates.
Python Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create FUNDING.yml Jul 1, 2019
copier Merge pull request #81 from pykong/refactor_render Oct 7, 2019
.travis.yml Add coveralls Sep 27, 2019 Merged origin/master to solve conflicts. Aug 29, 2019 Update Fix #69 Sep 27, 2019
pyproject.toml Submit to the Master Mold Jun 15, 2019
setup.cfg Submit to the Master Mold Jun 15, 2019

Think this library is awesome? Vote with a 👍 to include it in the awesome-python list:


Coverage Status Tests

A library for rendering projects templates.

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

Sample output

How to use

  • Use it in your Python code:
from copier import copy

# Create a project from a local path
copy("path/to/project/template", "path/to/destination")

# Or from a git URL.
copy("", "path/to/destination")

# You can also use "gh:" as a shortcut of ""
copy("gh:jpscaletti/copier.git", "path/to/destination")

# Or "gl:" as a shortcut of ""
copy("gl:jpscaletti/copier.git", "path/to/destination")
  • Or as a command-line tool:
copier path/to/project/template path/to/destination

How it works

The content of the files inside the project template is copied to the destination without changes, unless are suffixed with the extension '.tmpl'. In that case, the templating engine will be used to render them.

A slightly customized Jinja2 templating is used. The main difference is those variables are referenced with [[ name ]] instead of {{ name }} and blocks are [% if name %] instead of {% if name %}. To read more about templating see the Jinja2 documentation.

If a YAML file named copier.yml is found in the root of the project (alternatively, a YAML file named copier.yaml), the user will be prompted to fill in or confirm the default values.

Use the data argument to pass whatever extra context you want to be available in the templates. The arguments can be any valid Python value, even a function.

Since version 3.0, only Python 3.6 or later are supported. Please use the 2.5.1 version if your project runs on a previous Python version.

The copier.yml file

If a copier.yml, or copier.yaml file is found in the root of the project, it will be read and used for two purposes:

Prompt the user for information

For each key found, Copier will prompt the user to fill or confirm the values before they become available to the project template. So content like this:

name_of_the_project: My awesome project
number_of_eels: 1234
your_email: ""

will result in this series of questions:

name_of_the_project? [My awesome project]
your_email? []
number_of_eels? [1234] 42

NOTE: All values are required. If you want some value to be optional, do not use an empty string as the default value or copier will not allow you to continue without answering with a value. Use null instead, so you can press ENTER to accept the "empty" default value.

# DO NOT do this for optionals
bad_optional_value: ""

# DO THIS instead
good_optional_value: null

Arguments defaults

The keys _exclude, _include, _skip_if_exists, _tasks, and _extra_paths in the copier.yml file, will be treated as the default values for the exclude, include, tasks, and , extra_paths arguments to copier.copy().

Note that they become just the defaults, so any explicitly-passed argument will overwrite them.

# Shell-style patterns files/folders that must not be copied.
  - "*.bar"
  - ".git"
  - ".git/*"

# Shell-style patterns files/folders that *must be* copied, even if
# they are in the exclude list
  - ""

# Shell-style patterns files to skip, without asking, if they already exists
# in the destination folder

# Commands to be executed after the copy
  - "git init"
  - "rm [[ name_of_the_project ]]/"

# Additional paths, from where to search for templates
  - ~/Projects/templates

Warning: Use only trusted project templates as these tasks run with the same level of access as your user.







Uses the template in src_path to generate a new project at dst_path.


  • src_path (str):
    Absolute path to the project skeleton. Can be a version control system URL.

  • dst_path (str):
    Absolute path to where to render the skeleton.

  • data (dict):
    Data to be passed to the templates in addition to the user data from a copier.yml.

  • exclude (list):
    A list of names or shell-style patterns matching files or folders that must not be copied.

    To exclude a folder you should use two entries, one for the folder and the other for its content: [".git", ".git/*"].

  • include (list):
    A list of names or shell-style patterns matching files or folders that must be included, even if its name is a match for the exclude list. Eg: ['.gitignore']. The default is an empty list.

  • skip_if_exists (list):
    Skip any of these files, without asking, if another with the same name already exists in the destination folder. (it only makes sense if you are copying to a folder that already exists).

  • tasks (list):
    Optional lists of commands to run in order after finishing the copy. Like in the templates files, you can use variables on the commands that will be replaced by the real values before running the command. If one of the commands fails, the rest of them will not run.

  • envops (dict):
    Extra options for the Jinja template environment.

  • extra_paths (list):
    Additional paths, from where to search for templates. This is intended to be used with shared parent templates, files with macros, etc. outside the copied project skeleton.

  • pretend (bool):
    Run but do not make any changes.

  • force (bool):
    Overwrite files that already exist, without asking.

  • skip (bool):
    Skip files that already exist, without asking.

  • quiet (bool):
    Suppress the status output.

  • cleanup_on_error (bool):
    Remove the destination folder if the copy process or one of the tasks fail. True by default.

You can’t perform that action at this time.