Show changes in parameters between commits in the DVC repository, or between a commit and the workspace.
usage: dvc params diff [-h] [-q | -v] [--targets [<paths> [<paths> ...]]]
[--all] [--show-json] [--show-md] [--no-path]
[a_rev] [b_rev]
positional arguments:
a_rev Old Git commit to compare (defaults to HEAD)
b_rev New Git commit to compare (defaults to the
current workspace)
Provides a quick way to compare parameter values among experiments in the repository history. Requires that Git is being used to version the project params.
Parameter dependencies are defined in the
params
field ofdvc.yaml
(e.g. with the the-p
(--params
) option ofdvc run
).
Without arguments, this command compares parameters currently present in the
workspace (uncommitted changes) with the latest committed version.
This includes everything in params.yaml
(default parameters file) as well all
the params
used in dvc.yaml
. Values in dvc.lock
are used for comparison.
Only params that have changes are listed.
Note that unlike
dvc diff
, this command doesn't always need DVC files to find params files (see--targets
option). For that reason, it doesn't require an existing DVC project to run in. It can work in any Git repo.
--targets <paths>
- specific params files to compare. It accepts paths
to
any valid parameters file, regardless of whether dvc.yaml
is currently
tracking any params in them.
When specifying arguments for --targets
before a_rev
/b_rev
, you should
use --
after this option's arguments (POSIX terminals), e.g.:
$ dvc params diff --targets m1.json m2.yaml -- HEAD v1
--all
- prints all parameters including not changed.--show-json
- prints the command's output in easily parsable JSON format,
instead of a human-readable table.--show-md
- prints the command's output in the Markdown table format.-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.Let's create a simple YAML parameters file named params.yaml
(default params
file name, see dvc params
to learn more):
lr: 0.0041
train:
epochs: 70
layers: 9
process:
thresh: 0.98
bow: 15000
Define a pipeline stage with parameter dependencies:
$ dvc run -n train \
-d train.py -d users.csv -o model.pkl \
-p lr,train \
python train.py
Let's now print parameter values that we are tracking in this project:
$ dvc params diff
Path Param Old New
params.yaml lr — 0.0041
params.yaml process.bow — 15000
params.yaml process.thresh — 0.98
params.yaml train.epochs — 70
params.yaml train.layers — 9
The command above shows the difference in parameters between the workspace and
the last committed version of the params file params.yaml
. Since it did not
exist before, all Old
values are —
.
In a project with parameters file history (params present in various Git
commits), you will see both Old
and New
values. However, the parameters
won't be shown if there are no changes:
$ dvc params diff
Path Param Old New
params.yaml lr 0.0041 0.0043
params.yaml train.layers 9 7
params.yaml train.epochs 70 110
Specify --all
option to see all the parameters including not changed ones:
$ dvc params diff --all
Path Param Old New
params.yaml lr 0.0041 0.0043
params.yaml process.bow 15000 15000
params.yaml process.thresh 0.98 0.98
params.yaml train.layers 9 7
params.yaml train.epochs 70 110
To compare parameters with a specific commit, a tag or any revision can be specified, as an additional command line parameter:
$ dvc params diff e12b167
Path Param Old New
params.yaml lr 0.0038 0.0043
params.yaml train.epochs 70 110
Note that the train.layers
parameter disappeared because its value was not
changed between the current version in the workspace and the given one
(e12b167
).
To see the difference between two specific commits, both need to be specified:
$ dvc params diff e12b167 HEAD^
Path Param Old New
params.yaml lr 0.0038 0.0041
params.yaml train.layers 10 9
params.yaml train.epochs 50 70