Skip to content
Edit on GitHub

plots templates

Dump built-in plot templates to JSON files you can customize.


usage: dvc plots templates [-h] [-q | -v] [-o <path>]

positional arguments:
 TEMPLATE    Template to write. Writes all templates by default.


Some times you may need to customize the way dvc plots are rendered beyond what the built-in plot templates allow.dvc plots templates can dump these templates to JSON files for you use as base for new templates. To modify them, use any valid elements of the Vega-Lite specification.

You can dump a specific built-in template by providing it's name as argument, for example dvc plots templates confusion. Template files are written to .dvc/plots by default, but any location can be set with the --out (-o) option.

Note that templates can only be used with data-series plots.

Custom templates

Plot templates are Vega-Lite JSON specifications. They use predefined DVC anchors as placeholders for DVC to inject the plot values.

  • <DVC_METRIC_DATA> (required) - the plot data from any type of metrics files is converted to a single JSON array, and injected instead of this anchor. Two additional fields will be added: step and rev (explained below).

  • <DVC_METRIC_TITLE> (optional) - a title for the plot, that can be defined with the --title option of the dvc plots subcommands.

  • <DVC_METRIC_X> (optional) - field name of the data for the X axis. It can be defined with the -x option of the dvc plots subcommands. The auto-generated step field (explained below) is the default.

  • <DVC_METRIC_Y> (optional) - field name of the data for the Y axis. It can be defined with the -y option of the dvc plots subcommands. It defaults to the last header of the metrics file: the last column for CSV/TSV, or the last field for JSON/YAML.

  • <DVC_METRIC_X_LABEL> (optional) - field name to display as the X axis label

  • <DVC_METRIC_Y_LABEL> (optional) - field name to display as the Y axis label

File targets given to dvc plots show and dvc plots diff are treated as separate data series, each to be injected into a template file. There are two important fields that DVC adds to the plot data:

  • step - zero-based counter for the data rows/values. In many cases it corresponds to a machine learning training epoch number.

  • rev - This field helps distinguish between data sourced from different revisions, files or columns.


  • -o <path>, --out <path> - Directory to save templates to.

Example: Modifying the simple template

The built-in simple template can be an ideal base for custom templates because it has a minimal structure you can make quick modifications to. For example, let's show vertical bars instead of a connected line.

We'll work with the following data.csv file:


The simple template renders it like this:

$ dvc plots show data.csv --template simple

Let's dump the simple template to the current working directory and rename it appropriately:

$ dvc plots templates simple -o .
Templates have been written into '.'.

$ mv simple.json bars_template.json

Now, let's modify the bars_template.json file to display the bars (instead of a line):

$ cat bars_template.json
   "$schema": "",
   "mark": {
-    "type": "line"
+    "type": "bar"
   "encoding": { ...

And this is how the data looks like using our custom template:

$ dvc plots show data.csv --template bars_template.json


🐛 Found an issue? Let us know! Or fix it:

Edit on GitHub

Have a question? Join our chat, we will help you:

Discord Chat