Skip to main content
This command is deprecated. Use dvc stage add instead. All functionality from dvc run is available in the new command.

​
Synopsis

dvc run [options] command

​
Description

The dvc run command was used in earlier versions of DVC to create pipeline stages. It has been superseded by the more explicit and feature-rich dvc stage add command.

​
Why was it deprecated?

  • Clearer semantics: dvc stage add makes it explicit that you’re adding a stage to a pipeline
  • Better subcommand structure: The dvc stage command groups related functionality (add, list, etc.)
  • Improved consistency: Aligns with DVC’s overall command structure
  • Same functionality: All features from dvc run are available in dvc stage add

​
Migration Guide

Migrating from dvc run to dvc stage add is straightforward - the syntax is almost identical:

​
Basic command migration

Old syntax (dvc run): 
dvc run -n prepare -d data.csv -o prepared.csv python prepare.py
New syntax (dvc stage add): 
dvc stage add -n prepare -d data.csv -o prepared.csv python prepare.py
Simply replace dvc run with dvc stage add. All flags and options remain the same.

​
Complete migration examples

​
Example 1: Data preprocessing

Old: 
dvc run -n preprocess \
  -d raw/data.csv \
  -d src/preprocess.py \
  -o data/processed.csv \
  python src/preprocess.py
New: 
dvc stage add -n preprocess \
  -d raw/data.csv \
  -d src/preprocess.py \
  -o data/processed.csv \
  python src/preprocess.py

​
Example 2: Model training with parameters

Old: 
dvc run -n train \
  -d data/processed.csv \
  -d src/train.py \
  -p train.epochs,train.lr \
  -o models/model.pkl \
  -m metrics.json \
  python src/train.py
New: 
dvc stage add -n train \
  -d data/processed.csv \
  -d src/train.py \
  -p train.epochs,train.lr \
  -o models/model.pkl \
  -m metrics.json \
  python src/train.py

​
Example 3: Evaluation with plots

Old: 
dvc run -n evaluate \
  -d models/model.pkl \
  -d data/test.csv \
  -m scores.json \
  --plots confusion_matrix.csv \
  python evaluate.py
New: 
dvc stage add -n evaluate \
  -d models/model.pkl \
  -d data/test.csv \
  -m scores.json \
  --plots confusion_matrix.csv \
  python evaluate.py

​
Option Mapping

All options from dvc run are supported in dvc stage add:
FlagPurposeStatus
-n, --nameStage name✅ Same
-d, --depsDependencies✅ Same
-o, --outsOutputs (cached)✅ Same
-O, --outs-no-cacheOutputs (not cached)✅ Same
-p, --paramsParameter dependencies✅ Same
-m, --metricsMetrics outputs✅ Same
-M, --metrics-no-cacheMetrics (not cached)✅ Same
--plotsPlot outputs✅ Same
--plots-no-cachePlots (not cached)✅ Same
-f, --forceOverwrite existing stage✅ Same
-w, --wdirWorking directory✅ Same
--always-changedAlways run stage✅ Same
--descStage description✅ Same
There’s no functional difference between the flags - it’s a direct one-to-one mapping.

​
Automated Migration

If you have scripts or CI/CD pipelines using dvc run, you can quickly migrate them:

​
Using find and replace

# In your scripts
sed -i 's/dvc run/dvc stage add/g' *.sh

​
Updating Makefiles

Before: 
prepare:
	dvc run -n prepare -d data.csv -o prepared.csv python prepare.py
After: 
prepare:
	dvc stage add -n prepare -d data.csv -o prepared.csv python prepare.py

​
Updating CI/CD configurations

GitHub Actions (before): 
- name: Create pipeline
  run: dvc run -n train -d data.csv -o model.pkl python train.py
GitHub Actions (after): 
- name: Create pipeline
  run: dvc stage add -n train -d data.csv -o model.pkl python train.py

​
Frequently Asked Questions

​
Will my existing pipelines break?

No. The dvc run command created stages in dvc.yaml files using the same format that dvc stage add creates. Your existing pipeline files will continue to work with all DVC commands.

​
Do I need to recreate my pipelines?

No. Only the command to create stages has changed. Your existing stages in dvc.yaml don’t need any modifications.

​
Is dvc run completely removed?

While deprecated, dvc run may still work in some versions for backward compatibility. However, it’s recommended to migrate to dvc stage add as support will eventually be removed.

​
What about dvc.lock files?

The dvc.lock file format is unchanged. Both dvc run and dvc stage add produce identical lock files.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us