Skip to main content
DVC uses a hierarchical configuration system to manage project settings, remote storage, and various options. This guide explains the different configuration files and how they work together.

​
Configuration Files

DVC supports multiple configuration levels that shadow each other in a specific order:

System Config

System-wide settings for all users

Global Config

User-specific settings across all projects

Project Config

Repository-specific settings in .dvc/config

Local Config

Local overrides in .dvc/config.local (git-ignored)

​
Configuration Hierarchy

Configurations are merged in the following order (later levels override earlier ones):
  1. System (/etc/xdg/dvc/config on Linux)
  2. Global (~/.config/dvc/config on Linux)
  3. Project (.dvc/config - tracked by Git)
  4. Local (.dvc/config.local - not tracked by Git)
The local config file is git-ignored by default, making it perfect for storing sensitive information like access keys or user-specific paths.

​
DVC File Types

DVC uses several file types to manage your data and pipelines:

​
.dvc Files

.dvc files are single-stage files that track data files and directories. They contain metadata about:
  • File paths
  • MD5 checksums
  • Dependencies
  • Outputs
outs:
- md5: a304afb96060aad90176268345e10355
  size: 37891850
  path: model.pkl

​
dvc.yaml

dvc.yaml is a multi-stage pipeline file that defines:
  • Pipeline stages and their commands
  • Dependencies between stages
  • Parameters and metrics
  • Plots and artifacts
stages:
  train:
    cmd: python train.py
    deps:
      - train.py
      - data/train.csv
    params:
      - lr
      - epochs
    outs:
      - model.pkl

​
dvc.lock

dvc.lock is automatically generated to lock the state of your pipeline, including:
  • Exact checksums of all dependencies and outputs
  • Parameter values used
  • Command that was run
Don’t edit dvc.lock manually. It’s automatically managed by DVC to ensure reproducibility.

​
Configuration Sections

DVC configuration files use INI format with the following main sections:

​
core

General DVC behavior settings:
​
core.remote
string
Default remote storage to use for dvc push/dvc pull
​
core.autostage
boolean
default:"false"
Automatically stage changes to DVC files with Git
​
core.check_update
boolean
default:"true"
Check for DVC updates
​
core.analytics
boolean
default:"true"
Send anonymous usage analytics

​
cache

Local cache configuration:
​
cache.dir
string
Location of the cache directory (default: .dvc/cache)
​
cache.type
string
Link type for cache: reflink, hardlink, symlink, or copy
​
cache.shared
string
Make cache group-writable (group)

​
remote

Remote storage configurations. See Remote Configuration for details. 
['remote "myremote"']
    url = s3://mybucket/path
    region = us-east-1

​
state

The state section is deprecated and no longer used in recent DVC versions.

​
Working with Configuration

​
View Configuration

List all configuration values: 
dvc config --list
Show configuration with file origins: 
dvc config --list --show-origin

​
Set Configuration

Set a project-level configuration: 
dvc config core.remote myremote
Set a global configuration: 
dvc config --global user.name "John Doe"
Set a local (git-ignored) configuration: 
dvc config --local remote.myremote.access_key_id AKIAIOSFODNN7EXAMPLE

​
Unset Configuration

Remove a configuration value: 
dvc config --unset core.remote

​
Configuration Format

DVC configuration files use the INI format with special handling for named sections: 
[core]
    remote = myremote
    autostage = true

['remote "myremote"']
    url = s3://mybucket/path
    region = us-east-1

['remote "backup"']
    url = gs://backup-bucket
Named sections like remote and machine use double quotes in their section names to support spaces and special characters.

​
Best Practices

Store sensitive credentials in .dvc/config.local which is git-ignored:
dvc config --local remote.storage.access_key_id YOUR_KEY
dvc config --local remote.storage.secret_access_key YOUR_SECRET
Configure the default remote in .dvc/config (tracked by Git):
dvc config core.remote storage
This ensures all team members use the same default remote.
For local remotes, use relative paths to make the configuration portable:
dvc config remote.storage.url ../shared-storage
Use descriptive names for different storage purposes:
dvc remote add storage s3://production-data
dvc remote add backup s3://backup-bucket  
dvc remote add shared /mnt/shared

​
Next Steps

DVC Files

Deep dive into .dvc and dvc.yaml file formats

Remote Config

Configure remote storage for your data

Build docs developers (and LLMs) love

Get started for freeTalk to us