KiCad Reference manual - Project templates - 《KiCad v6.0 Documentation》

Project templates

Project templates

Using a project template facilitates setting up a new project with predefined settings. Templates may contain pre-defined board outlines, connector positions, schematic elements, design rules, etc. Complete schematics and/or PCBs used as seed files for the new project may even be included.

Using templates

The File → New Project → New Project from Template menu will open the Project Template Selector dialog:

A single click on a template’s icon will display the template information, and a further click on the OK button creates the new project. The template files will be copied to the new project location and renamed to reflect the new project’s name.

After selection of a template:

Template Locations:

KiCad looks for template files in the following paths:

path defined in the environment variable KICAD_USER_TEMPLATE_DIR
path defined in the environment variable KICAD_TEMPLATE_DIR
System templates: <kicad bin dir>/../share/kicad/template/
User templates:
- Unix: ~/kicad/template/
- Windows: C:\Documents and Settings\username\My Documents\kicad\template or C:\Users\username\Documents\kicad\template
- Mac: ~/Documents/kicad/template/

Creating templates

The template name is the directory name where the template files are stored. The metadata directory is a subdirectory named meta containing files describing the template.

The metadata consists of one required file, and may contain optional files. All files must be created by the user using a text editor or previous KiCad project files, and placed into the required directory structure.

All files and directories in a template are copied to the new project path when a project is created using a template, except meta. Files and directories containing the template name will be renamed with the new project file name.

For example, creating a project called newproject from a template named example:

Files in template example directory	Files created in project newproject directory
example.kicad_pro example.kicad_sch example.kicad_pcb example-first.kicad_sch second-example.kicad_sch third.kicad_sch third.kicad_pcb	newproject.kicad_pro newproject.kicad_sch newproject.kicad_pcb newproject-first.kicad_sch second-newproject.kicad_sch third.kicad_sch third.kicad_pcb

A template does not need to contain a complete project, if a required project file is missing, KiCad will create it using its default create project behavior:

Files in template example directory	Files created in newproject directory
example.kicad_sch first-example.kicad_sch first-example.kicad_pcb second-example.kicad_sch second-example.kicad_pcb	newproject.kicad_sch first-newproject.kicad_sch first-newproject.kicad_pcb second-newproject.kicad_sch second-newproject.kicad_pcb newproject.kicad_pro (default) newproject.kicad_pcb (default)

As an exception to the template name renaming rule, if one project file (.kicad_pro) exists and its name doesn’t match the template name, KiCad will do the renaming based on that project file name instead:

Files in template example directory	Files created in newproject directory
example.kicad_sch example.kicad_pcb first-example.kicad_pro first-example.kicad_sch first-example.kicad_pcb second-example.kicad_sch second-example.kicad_pcb	example.kicad_sch example.kicad_pcb newproject.kicad_pro newproject.kicad_sch newproject.kicad_pcb second-example.kicad_sch second-example.kicad_pcb

It is not recommended to create a template with multiple project files.

Template example

Here is an example showing project files for raspberrypi-gpio template:

And the metadata files:

Required File:

meta/info.html

HTML-formatted information describing the template.

The <title> tag determines the actual name of the template that is exposed to the user for template selection. Note that the project template name will be cut off if it’s too long.

Using HTML means that images can be easily in-lined without having to invent a new scheme. Only basic HTML tags can be used in this document.

Here is a sample info.html file:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html;
charset=windows-1252">
<TITLE>Raspberry Pi - Expansion Board</TITLE>
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<P>This project template is the basis of an expansion board for the
<A HREF="http://www.raspberrypi.org/" TARGET="blank">Raspberry Pi $25
ARM board.</A> <BR><BR>This base project includes a PCB edge defined
as the same size as the Raspberry-Pi PCB with the connectors placed
correctly to align the two boards. All IO present on the Raspberry-Pi
board is connected to the project through the 0.1&quot; expansion
headers. <BR><BR>The board outline looks like the following:
</P>
<P><IMG SRC="brd.png" NAME="brd" ALIGN=BOTTOM WIDTH=680 HEIGHT=378
BORDER=0><BR><BR><BR><BR>
</P>
<P>(c)2012 Brian Sidebotham<BR>(c)2012 KiCad Developers</P>
</BODY>
</HTML>

Optional Files:

meta/icon.png

A 64 x 64 pixel PNG icon file which is used as a clickable icon in the template selection dialog.

Any other image files used by meta/info.html, such as the image of the board file in the dialog above, are placed in this folder as well.