dvc config

Get or set config options

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]

List All Config

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.

Related Commands

• dvc remote - Specialized commands for remote configuration
• dvc cache - Specialized commands for cache configuration
• dvc init - Initialize DVC repository with default config