Skip to main content

​
Synopsis

dvc status [options] [<targets>...]

​
Description

The dvc status command shows the status of your DVC-tracked files and pipeline stages. It helps you understand:
  • Which tracked files have been modified in your workspace
  • Which pipeline stages need to be reproduced
  • Differences between local cache and remote storage (with --cloud option)
  • What data needs to be pushed or pulled
The command operates in two main modes:
  1. Local mode (default): Shows which files/stages have changed in your workspace
  2. Cloud mode (--cloud): Compares your local cache with remote storage
Think of dvc status as similar to git status - it shows what has changed without making any modifications.

​
Options

​
targets
path
Limit command scope to specific tracked files/directories, .dvc files, or stage names.
dvc status data/train.csv models/
​
-q, --quiet
boolean
default:"false"
Suppresses all output. Exit with 0 if pipelines are up to date, otherwise 1. Useful for scripts and CI/CD.
dvc status --quiet && echo "All up to date"
​
-c, --cloud
boolean
default:"false"
Show status of local cache compared to remote repository. Shows what needs to be pushed or pulled.
dvc status --cloud
​
-r, --remote
string
Remote storage to compare local cache to. Used with --cloud.
dvc status --cloud --remote s3storage
​
-j, --jobs
integer
default:"4 * cpu_count()"
Number of jobs to run simultaneously when checking status.
​
-a, --all-branches
boolean
default:"false"
Show status for all Git branches. Used with --cloud.
dvc status --cloud --all-branches
​
-T, --all-tags
boolean
default:"false"
Show status for all Git tags. Used with --cloud.
​
-A, --all-commits
boolean
default:"false"
Show status for all Git commits. Used with --cloud.
This can be very slow for repositories with many commits.
​
-d, --with-deps
boolean
default:"false"
Show status for all dependencies of the specified target.
dvc status --with-deps train.dvc
​
-R, --recursive
boolean
default:"false"
Show status of all stages in the specified directory.
​
--json
boolean
default:"false"
Show status in JSON format. Useful for parsing in scripts.
dvc status --json
​
--no-updates
boolean
default:"false"
Ignore updates to imported data.

​
Examples

​
Basic status check

Check the status of all tracked data: 
dvc status

Data and pipelines are up to date.
Or if there are changes: 
train.dvc:
        changed deps:
                modified:           data/raw.csv
        changed outs:
                not in cache:       models/model.pkl

​
Check specific files

Check status of specific targets: 
dvc status data/processed.csv.dvc

data/processed.csv.dvc:
        changed outs:
                modified:           data/processed.csv

​
Cloud status

Compare local cache with remote storage: 
dvc status --cloud

new:            data/train.csv
new:            models/model.pkl
This shows files that exist locally but haven’t been pushed to remote storage. Or if pulling is needed: 
deleted:        data/old_dataset.csv
new:            data/new_dataset.csv

​
Compare with specific remote

dvc status --cloud --remote myremote

Cache and remote 'myremote' are in sync.

​
Check pipeline dependencies

Check a stage and all its dependencies: 
dvc status --with-deps evaluate.dvc

preprocess.dvc:
        changed deps:
                modified:           data/raw.csv

train.dvc:
        changed deps:
                modified:           data/processed.csv

​
JSON output

Get status in JSON format for programmatic use: 
dvc status --json

{
  "train.dvc": {
    "changed deps": {
      "data/raw.csv": "modified"
    },
    "changed outs": {
      "models/model.pkl": "not in cache"
    }
  }
}

​
Quiet mode for scripting

Use in CI/CD or scripts: 
if dvc status --quiet; then
    echo "Everything is up to date"
else
    echo "Changes detected, running pipeline"
    dvc repro
fi

​
Check all branches

See what needs to be synced across all branches: 
dvc status --cloud --all-branches

main:
        new:            models/model_v1.pkl

experiment:
        new:            models/model_v2.pkl
        new:            data/experiment_data.csv

​
Understanding status output

​
Local mode status states

StateMeaning
modifiedFile content has changed
not in cacheFile is tracked but not in cache (needs dvc commit)
deletedFile has been deleted from workspace
changed depsDependencies of a stage have changed
changed outsOutputs of a stage have changed

​
Cloud mode status states

StateMeaning
newFile is in local cache but not in remote (need to dvc push)
deletedFile is in remote but not in local cache (need to dvc pull)

​
Example workflows

​
Workflow 1: Before committing

# Check what has changed
dvc status

# Commit changes if needed
dvc commit

# Update Git
git add *.dvc
git commit -m "Update data"

​
Workflow 2: Syncing with remote

# Check what needs to be synced
dvc status --cloud

# Push new data to remote
dvc push

# Verify sync
dvc status --cloud

​
Workflow 3: Pipeline development

# Check pipeline status
dvc status

# If dependencies changed, reproduce
if ! dvc status --quiet; then
    dvc repro
fi

# Check cloud sync
dvc status --cloud

​
When nothing changes

If everything is up to date, you’ll see: 
Data and pipelines are up to date.
Or for cloud mode: 
Cache and remote 'origin' are in sync.
Or if the project is new: 
There are no data or pipelines tracked in this project yet.
See https://dvc.org/doc/start to get started!

​
Performance tips

Use targets - Check specific targets rather than the entire project to get faster results.
Adjust jobs - Use --jobs to control parallelism. More jobs = faster but more resource-intensive.
Avoid —all-commits - This option can be extremely slow for large repositories. Use --all-branches or --all-tags instead when possible.
  • dvc diff - Show detailed differences between commits
  • dvc commit - Record changes to tracked files
  • dvc push - Upload data to remote storage
  • dvc pull - Download data from remote storage
  • dvc checkout - Update workspace from cache

Build docs developers (and LLMs) love

Get started for freeTalk to us