Edit on GitHub

plots diff

Show multiple versions of plot metrics by plotting them in a single image. This allows to easily compare them.


usage: dvc plots diff [-h] [-q | -v] [--targets [<path> [<path> ...]]]
                      [-t <name_or_path>] [-x <field>] [-y <field>]
                      [--no-header] [--title <text>]
                      [--x-label <text>] [--y-label <text>] [-o <path>]
                      [revisions [revisions ...]]

positional arguments:
  revisions             Git commits to find metrics to compare


This command is a way to visualize the "difference" between metrics among experiments in the repository history, by plotting multiple versions of the metrics. All plots defined in dvc.yaml are used by default.

Note that unlike dvc metrics diff, this command does not calculate numeric differences between metric file values.

revisions are Git commit hashes, tag, or branch names. If none are specified, dvc plots diff compares targets currently present in the workspace (uncommitted changes) with their latest committed versions (required). A single specified revision results in comparing the workspace and that version.

Note that any number of revisions can be provided, and the resulting plot shows all of them in a single output.

The plot style can be customized with plot templates, using the --template option. To learn more about metric file formats and templates please see dvc plots.

Note that the default behavior of this command can be modified per metrics file with dvc plots modify.


  • --targets <path> - specific metric files to visualize. These must be listed in a dvc.yaml file (see the --plots option of dvc run). When specifying arguments for --targets before revisions, you should use -- after this option's arguments, e.g.:

    $ dvc plots diff --targets t1.json t2.csv -- HEAD v1 v2

    Alternatively, you can also run the above statement as:

    $ dvc plots diff HEAD v1 v2 --targets t1.json t2.csv
  • -o <path>, --out <path> - name of the generated file. By default, the output file name is equal to the input filename with a .html file extension (or .json when using --show-vega).
  • -t <name_or_path>, --template <name_or_path> - plot template to be injected with data. The default template is .dvc/plots/default.json. See more details in dvc plots.
  • -x <field> - field name from which the X axis data comes from. An auto-generated index field is used by default. See Custom templates for more information on this index field. Column names or numbers are expected for tabular metric files.
  • -y <field> - field name from which the Y axis data comes from. The last field found in the --targets is used by default. Column names or numbers are expected for tabular metric files.
  • --x-label <text> - X axis label. The X field name is the default.
  • --y-label <text> - Y axis label. The Y field name is the default.
  • --title <text> - plot title.
  • --show-vega - produce a Vega specification file instead of HTML. See dvc plots for more info.
  • --no-header - lets DVC know that CSV or TSV --targets do not have a header. A 0-based numeric index can be used to identify each column instead of names.
  • -h, --help - prints the usage/help message, and exit.
  • -q, --quiet - do not write anything to standard output. Exit with 0 if no problems arise, otherwise 1.
  • -v, --verbose - displays detailed tracing information.


To compare uncommitted changes of a metrics file and its last committed version:

$ dvc plots diff --targets logs.csv --x-label x

Note that we renamed the X axis label with option --x-label x.

Compare two specific versions (commit hashes, tags, or branches):

$ dvc plots diff HEAD 0135527 --targets logs.csv

Example: Confusion matrix

We'll use tabular metrics file classes.csv for this example:


The predefined confusion matrix template (in .dvc/plots/confusion.json) shows how metric comparisons can be faceted by separate plots. It can be enabled with -t (--template):

$ dvc plots diff -t confusion --targets classes.csv -x predicted


๐Ÿ› Found an issue? Let us know! Or fix it:

Edit on GitHub

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

Discord Chat