dvc status

Show changed stages and compare local cache with remote storage

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

State	Meaning
modified	File content has changed
not in cache	File is tracked but not in cache (needs dvc commit)
deleted	File has been deleted from workspace
changed deps	Dependencies of a stage have changed
changed outs	Outputs of a stage have changed

Cloud mode status states

State	Meaning
new	File is in local cache but not in remote (need to dvc push)
deleted	File 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.

Related commands

• 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