> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/treeverse/dvc/llms.txt
> Use this file to discover all available pages before exploring further.
# dvc exp diff
> Compare metrics and parameters between two experiments
## Description
Compare the metrics and parameters between two experiments or revisions. This command provides a focused comparison showing what changed between two specific runs, making it easy to understand the impact of parameter changes on model performance.
Use `dvc exp diff` after running an experiment to quickly see how it compares to your baseline.
## Usage
```bash theme={null}
dvc exp diff [a_rev] [b_rev] [options]
```
## Arguments
Old experiment or Git revision to compare. Defaults to HEAD if not specified.
Can be:
* Experiment name (e.g., `exp-a1b2c`)
* Git commit SHA
* Git branch name
* Git tag
```bash theme={null}
dvc exp diff main
dvc exp diff exp-baseline
```
New experiment or Git revision to compare. Defaults to the current workspace.
```bash theme={null}
dvc exp diff main feature-branch
dvc exp diff exp-a1b2c exp-d3e4f
```
## Options
Show unchanged metrics and parameters as well. By default, only changed values are displayed.
```bash theme={null}
dvc exp diff --all
```
Show only parameters that are stage dependencies (defined in `dvc.yaml`).
```bash theme={null}
dvc exp diff --param-deps
```
Show output in JSON format for programmatic processing.
```bash theme={null}
dvc exp diff --json > diff.json
```
Show output in Markdown table format (GitHub Flavored Markdown).
```bash theme={null}
dvc exp diff --md
```
Don't show the metric/parameter file path in output.
```bash theme={null}
dvc exp diff --no-path
```
Round metrics to N digits after the decimal point.
```bash theme={null}
dvc exp diff --precision 3
```
## Examples
### Compare workspace with HEAD
```bash theme={null}
dvc exp diff
```
Output:
```bash theme={null}
Metric
──────────────────────────────────────────────────
Path Metric HEAD workspace diff
──────────────────────────────────────────────────
metrics.json accuracy 0.89 0.92 +0.03
metrics.json loss 0.287 0.234 -0.053
Param
──────────────────────────────────────────────────
Path Param HEAD workspace
──────────────────────────────────────────────────
params.yaml train.lr 0.01 0.001
params.yaml train.epochs 50 80
```
Positive diff values indicate improvement in metrics (when higher is better).
### Compare two specific experiments
```bash theme={null}
dvc exp diff exp-baseline exp-new-model
```
Output:
```bash theme={null}
Metric
────────────────────────────────────────────────────────────────
Path Metric exp-baseline exp-new-model diff
────────────────────────────────────────────────────────────────
metrics.json accuracy 0.85 0.92 +0.07
metrics.json f1_score 0.83 0.90 +0.07
metrics.json loss 0.312 0.234 -0.078
Param
────────────────────────────────────────────────────────────────
Path Param exp-baseline exp-new-model
────────────────────────────────────────────────────────────────
params.yaml model.architecture resnet18 resnet50
params.yaml train.lr 0.1 0.001
params.yaml train.batch_size 32 64
```
Experiment names support tab completion for easier command-line usage.
### Show all metrics including unchanged
```bash theme={null}
dvc exp diff --all
```
Output:
```bash theme={null}
Metric
──────────────────────────────────────────────────
Path Metric HEAD workspace diff
──────────────────────────────────────────────────
metrics.json accuracy 0.89 0.92 +0.03
metrics.json loss 0.287 0.234 -0.053
metrics.json val_loss 0.312 0.312 0
Param
──────────────────────────────────────────────────
Path Param HEAD workspace
──────────────────────────────────────────────────
params.yaml train.lr 0.01 0.001
params.yaml train.epochs 50 80
params.yaml model.dropout 0.5 0.5
params.yaml random_seed 42 42
```
Unchanged values have a diff of 0 or show the same value in both columns.
### Hide file paths
```bash theme={null}
dvc exp diff --no-path
```
Output:
```bash theme={null}
Metric
────────────────────────────────────────
Metric HEAD workspace diff
────────────────────────────────────────
accuracy 0.89 0.92 +0.03
loss 0.287 0.234 -0.053
Param
────────────────────────────────────────
Param HEAD workspace
────────────────────────────────────────
train.lr 0.01 0.001
train.epochs 50 80
```
### Export to JSON
```bash theme={null}
dvc exp diff --json
```
Output:
```json theme={null}
{
"metrics": {
"metrics.json": {
"accuracy": {
"old": 0.89,
"new": 0.92,
"diff": 0.03
},
"loss": {
"old": 0.287,
"new": 0.234,
"diff": -0.053
}
}
},
"params": {
"params.yaml": {
"train.lr": {
"old": 0.01,
"new": 0.001
},
"train.epochs": {
"old": 50,
"new": 80
}
}
}
}
```
JSON format is perfect for integrating with CI/CD pipelines or custom analysis scripts.
### Format as Markdown table
```bash theme={null}
dvc exp diff --md
```
Output:
```markdown theme={null}
## Metric
| Path | Metric | HEAD | workspace | diff |
|--------------|----------|-------|-----------|--------|
| metrics.json | accuracy | 0.89 | 0.92 | +0.03 |
| metrics.json | loss | 0.287 | 0.234 | -0.053 |
## Param
| Path | Param | HEAD | workspace |
|-------------|--------------|------|----------|
| params.yaml | train.lr | 0.01 | 0.001 |
| params.yaml | train.epochs | 50 | 80 |
```
### Compare with custom precision
```bash theme={null}
dvc exp diff --precision 2
```
Output:
```bash theme={null}
Metric
──────────────────────────────────────────────────
Path Metric HEAD workspace diff
──────────────────────────────────────────────────
metrics.json accuracy 0.89 0.92 +0.03
metrics.json loss 0.29 0.23 -0.05
```
### Compare branches
```bash theme={null}
dvc exp diff main feature-branch
```
Both revisions must exist in your Git history or be valid experiment names.
## Understanding the Output
### Metrics Table
The metrics table shows:
* **Path**: File containing the metric (e.g., `metrics.json`)
* **Metric**: Metric name within the file
* **Old value**: Metric value in first revision
* **New value**: Metric value in second revision
* **Diff**: Numerical difference (new - old)
### Parameters Table
The parameters table shows:
* **Path**: File containing the parameter (e.g., `params.yaml`)
* **Param**: Parameter name within the file
* **Old value**: Parameter value in first revision
* **New value**: Parameter value in second revision
Parameters don't show a diff because they're often non-numeric values.
## Common Workflows
### Quick experiment validation
```bash theme={null}
# Run experiment with new parameters
dvc exp run -S train.lr=0.001
# Compare with baseline
dvc exp diff
```
### A/B testing
```bash theme={null}
# Compare two competing approaches
dvc exp diff exp-approach-a exp-approach-b --md > comparison.md
```
### CI/CD integration
```bash theme={null}
# Export diff as JSON for automated checks
dvc exp diff --json > diff.json
# Check if accuracy improved
accuracy_diff=$(jq '.metrics."metrics.json".accuracy.diff' diff.json)
if (( $(echo "$accuracy_diff > 0" | bc -l) )); then
echo "Accuracy improved!"
fi
```
### Documentation generation
```bash theme={null}
# Generate markdown report of improvements
dvc exp diff v1.0 v2.0 --md --all > CHANGELOG_metrics.md
```
## Related Commands
* `dvc exp show` - View all experiments in a table
* `dvc exp run` - Create new experiments to compare
* `dvc metrics diff` - Compare metrics without experiment context
* `dvc params diff` - Compare parameters without experiment context