Skip to main content

​
Description

The dvc config command allows you to view and modify DVC configuration settings. Configuration can be set at different levels (local, project, global, system) and controls behavior like remote storage, cache settings, and user preferences.

​
Usage

dvc config [options] [name] [value]

dvc config --list

​
Arguments

​
name
string
Option name in format:
  • section.option - For core settings (e.g., core.autostage)
  • remote.name.option - For remote settings (e.g., remote.storage.url)
  • db.name.option - For database settings
​
value
string
Value to set for the option. Omit to get current value.

​
Options

​
-u, --unset
flag
Unset (remove) the specified option.
​
-l, --list
flag
List all defined config values.
​
--show-origin
flag
Show the source file containing each config value.

​
Configuration Levels

​
--local
flag
Use local config (.dvc/config.local).Not tracked by Git - Use for machine-specific settings and credentials.
​
--project
flag
Use project config (.dvc/config).Tracked by Git - Use for project-wide settings shared across team.
​
--global
flag
Use global config (~/.config/dvc/config).User-wide settings across all DVC projects.
​
--system
flag
Use system config (/etc/dvc/config).System-wide settings for all users.

​
Examples

​
List All Configuration

$ dvc config --list

core.remote=storage
core.autostage=true
cache.type=hardlink
remote.storage.url=s3://mybucket/dvc-storage

​
List Config with Origins

$ dvc config --list --show-origin

.dvc/config     core.remote=storage
.dvc/config     core.autostage=true
.dvc/config     remote.storage.url=s3://mybucket/dvc-storage
.dvc/config.local       remote.storage.access_key_id=AKIA...
The --show-origin flag shows which config file contains each setting, helpful for debugging configuration issues.

​
Get Specific Value

$ dvc config core.remote

storage

​
Set Core Options

# Enable autostage (auto stage dvc.lock changes)
dvc config core.autostage true

# Set default remote
dvc config core.remote storage

# Disable analytics
dvc config core.analytics false

# Check updates on startup
dvc config core.check_update true

​
Configure Remote Storage

# Set remote URL (project level, tracked by Git)
dvc config remote.storage.url s3://mybucket/dvc-storage

# Set credentials (local level, NOT tracked by Git)
dvc config --local remote.storage.access_key_id AKIAIOSFODNN7EXAMPLE
dvc config --local remote.storage.secret_access_key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Set region
dvc config remote.storage.region us-east-1
Security: Always use --local flag when setting credentials. Local config is not tracked by Git.

​
Configure Cache Settings

# Set cache directory
dvc config cache.dir /mnt/external/dvc-cache

# Set cache type (hardlink, symlink, reflink, copy)
dvc config cache.type hardlink

# Enable protected mode (read-only cache files)
dvc config cache.protected true

# Enable shared cache for multiple users
dvc config cache.shared group

​
Unset Configuration

# Remove a setting
dvc config core.autostage --unset

# Remove remote credentials
dvc config --local remote.storage.access_key_id --unset

​
Global Configuration

# Set global cache directory for all projects
dvc config --global cache.dir ~/shared-dvc-cache

# Disable analytics globally
dvc config --global core.analytics false

​
Common Configuration Options

​
Core Settings

​
core.remote
string
Default remote storage name.
​
core.autostage
boolean
Automatically stage dvc.lock and .gitignore changes.
​
core.analytics
boolean
Enable anonymous usage analytics.
​
core.check_update
boolean
Check for DVC updates on startup.
​
core.no_scm
boolean
Use DVC without Git or other SCM.

​
Cache Settings

​
cache.dir
string
Custom cache directory location.
​
cache.type
string
File link type: hardlink, symlink, reflink, or copy.
​
cache.protected
boolean
Make cache files read-only to prevent accidental modification.
​
cache.shared
string
Enable cache sharing: group or all.

​
Remote Settings

​
remote.<name>.url
string
Remote storage URL.
​
remote.<name>.access_key_id
string
AWS access key ID (S3 remotes).
​
remote.<name>.secret_access_key
string
AWS secret access key (S3 remotes).
​
remote.<name>.region
string
AWS region (S3 remotes).
​
remote.<name>.profile
string
AWS profile name.
​
remote.<name>.endpointurl
string
Custom S3 endpoint URL.

​
Plots Settings

​
plots.html_template
string
Custom HTML template for plot visualization.
​
plots.auto_open
boolean
Automatically open plots in browser.
​
plots.out_dir
string
Default output directory for plots.

​
Configuration Levels (Precedence)

Configuration is read in the following order (later overrides earlier):
1

System Config (/etc/dvc/config)

System-wide settings for all users.
2

Global Config (~/.config/dvc/config)

User-wide settings across all projects.
3

Project Config (.dvc/config)

Project-specific settings, tracked by Git.
4

Local Config (.dvc/config.local)

Machine-specific settings, NOT tracked by Git.
Best Practice:
  • Project settings (URLs, shared options) → .dvc/config (tracked)
  • Credentials and machine-specific settings → .dvc/config.local (not tracked)
  • Personal preferences → ~/.config/dvc/config (global)

​
Configuration File Format

DVC config files use INI format:
.dvc/config
[core]
    remote = storage
    autostage = true

[remote "storage"]
    url = s3://mybucket/dvc-storage
    region = us-east-1

[cache]
    type = hardlink
    protected = true
.dvc/config.local
[remote "storage"]
    access_key_id = AKIAIOSFODNN7EXAMPLE
    secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

​
Use Cases

Team Collaboration

Set project-wide defaults in .dvc/config for consistent team experience.

Secure Credentials

Store sensitive credentials in .dvc/config.local (not tracked by Git).

Personal Preferences

Configure global settings for your workflow across all projects.

CI/CD Setup

Configure system-level cache locations and credentials for build servers.

​
Environment Variables

DVC config can also be set via environment variables: 
# Override remote URL
export DVC_REMOTE_STORAGE_URL=s3://mybucket/dvc-storage

# Set credentials
export DVC_REMOTE_STORAGE_ACCESS_KEY_ID=AKIA...
export DVC_REMOTE_STORAGE_SECRET_ACCESS_KEY=wJalr...

# Disable analytics
export DVC_CORE_ANALYTICS=false
Format: DVC_<SECTION>_<NAME>_<OPTION> (uppercase)
Environment variables have the highest precedence and override all config files.

​
Troubleshooting

​
View Effective Configuration

# See all config values and where they come from
dvc config --list --show-origin

​
Reset to Defaults

# Remove all custom settings
rm .dvc/config.local
dvc config --list --unset

​
Config Not Found Error

ERROR: Not inside a DVC repo
Solution: Some config levels (project, local) require being inside a DVC repository.
  • dvc remote - Specialized commands for remote configuration
  • dvc cache - Specialized commands for cache configuration
  • dvc init - Initialize DVC repository with default config

Build docs developers (and LLMs) love

Get started for freeTalk to us