config
Get or set project-level (or global) DVC configuration options.
Synopsis
usage: dvc config [-h] [--global | --system | --project | --local]
[-q | -v] [-u]
[-l] [--show-origin] [name] [value]
positional arguments:
name Option name in format: section.option or remote.name.option
e.g. 'core.check_update', 'cache.dir', 'remote.myremote.url'
value Option value.
Description
You can query/set/replace/unset DVC configuration options with this command. It
takes a config option name
(a config section and a key, separated by a dot)
and its value
(any valid alpha-numeric string generally).
When reading config options (no value
is given or --list
is used), the
values are read from a combined set of values from the system, global, project,
and local config files (in that order). The --system
, --global
, --project
,
and --local
options can be used to read from that configuration only.
When writing (a value
is given or --unset
is used), the new value is written
to the project-level config file by default (.dvc/config
). Options --system
,
--global
and --local
can be used to write to that location instead.
.dvc/config
is meant to be tracked by Git and should not contain sensitive
user info or secrets (passwords, SSH keys, etc). Use --local
when in doubt.
Flag | Priority | Config file location |
---|---|---|
--local | 1 | .dvc/config.local |
None or --project (default) | 2 | .dvc/config |
The --global
and --system
flags are also useful to set config options for
multiple projects or users, respectively.
Flag | Priority | macOS location | Linux location (typical*) | Windows location |
---|---|---|---|---|
--global | 3 | $HOME/Library/Application\ Support/dvc/config | $HOME/.config/dvc/config | %LocalAppData%\iterative\dvc\config |
--system | 4 | /Library/Application\ Support/dvc/config | /etc/xdg/dvc/config | %AllUsersProfile%\Application Data\iterative\dvc\config |
* For Linux, the global
dvc/config
may be found in$XDG_CONFIG_HOME
, and the system-wide one in$XDG_CONFIG_DIRS[0]
, if those env vars are defined.
Note that the
--show-origin
flag can show you where a given config optionvalue
is currently stored.
Command options (flags)
-
-u
,--unset
- remove the specified config optionname
from a config file. Don't provide avalue
argument when employing this flag. -
--system
- modify the system config file (e.g./etc/xdg/dvc/config
) instead of.dvc/config
. Useful to apply config options to all the projects (all users) in the machine. May require superuser access e.g.sudo dvc config --system ...
(Linux). -
--global
- modify the global config file (e.g.~/.config/dvc/config
) instead of the project's.dvc/config
. Useful to apply config options to all your projects. -
--project
- only use the project's config file (.dvc/config
) when reading config values (this is the default when writing). -
--local
- use the Git-ignored local config file (located in.dvc/config.local
) instead of.dvc/config
. This is useful to save private config values that you don't want to track and share with Git (credentials, private locations, etc.). -
-l
,--list
- lists all defined config values. -
--show-origin
- when listing or getting config options, also show the location of the config file where each optionvalue
is found. -
-h
,--help
- prints the usage/help message, and exit. -
-q
,--quiet
- do not write anything to standard output. Exit with 0 if no problems arise, otherwise 1. -
-v
,--verbose
- displays detailed tracing information.
Configuration sections
The following config sections are written by this command to the appropriate
config file (.dvc/config
by default), supporting different config options
within:
core
- main section with the general config optionsremote
- sections in the config file that describe particular remotescache
- options that affect the project's cacheexp
- options to change the default repo paths assumed bydvc exp init
hydra
- options around Hydra Composition for experiment configuration.parsing
- options around the parsing of dictionary unpacking.plots
- options for configuringdvc plots
.state
- see Internal directories and files to learn more about the state database.index
- see Internal directories and files to learn more about remote index files.
core
-
core.remote
- name of the remote storage to use by default. -
core.interactive
- whether to always ask for confirmation before reproducing each stage indvc repro
. (Normally, this behavior requires using the-i
option of that command.) Accepts values:true
andfalse
. -
core.analytics
- used to turn off anonymized usage statistics. Accepts valuestrue
(default) andfalse
. -
core.checksum_jobs
- number of threads for computing file hashes. Accepts positive integers. The default value ismax(1, min(4, cpu_count() // 2))
. -
core.hardlink_lock
- use hardlink file locks instead of the default ones, based onflock
(i.e. project lock file.dvc/lock
). Accepts valuestrue
andfalse
(default). Useful when the DVC project is on a file system that doesn't properly support file locking (e.g. NFS v3 and older). -
core.no_scm
- tells DVC to not expect or integrate with Git (even if the project is initialized inside a Git repo). Accepts valuestrue
andfalse
(default). Set with the--no-scm
option ofdvc init
(more details). -
core.check_update
- disable/enable DVC's automatic update checks, which notify the user when a new version is available. Accepts valuestrue
(default) andfalse
. -
core.autostage
- if enabled, DVC will automatically stage (git add
) DVC files created or modified by DVC commands. The files will not be committed. Accepts valuestrue
andfalse
(default).
remote
Unlike most other sections, configuration files may have more than one
'remote'
. All of them require a unique "name"
and a url
value. They can
also specify jobs
, verify
, and many platform-specific key/value pairs like
port
and password
.
See Remote Storage Configuration for more details.
For example, the following config file defines a temp
remote in the local file
system (located in /tmp/dvcstore
), and marked as default (via core
section):
['remote "temp"']
url = /tmp/dvcstore
[core]
remote = temp
cache
-
cache.dir
- set/unset cache directory location. A correct value is either an absolute path, or a path relative to the config file location. The default value iscache
, that resolves to.dvc/cache
(relative to the project config file location).See also the helper command
dvc cache dir
to intuitively set this config option, properly transforming paths relative to the current working directory into paths relative to the config file location. -
cache.type
- link type that DVC should use to link data files from cache to the workspace. Possible values:reflink
,symlink
,hardlink
,copy
or an ordered combination of those, separated by commas e.g:reflink,hardlink,copy
. Default:reflink,copy
There are pros and cons to different link types. Refer to File link types for a full explanation of each one.
If you set
cache.type
tohardlink
orsymlink
, manually modifying tracked data files in the workspace would corrupt the cache. To prevent this, DVC automatically protects those kinds of links (making them read-only). Usedvc unprotect
to be able to modify them safely.To apply changes to this config option in the workspace, restore all file links/copies from cache with
dvc checkout --relink
. -
cache.slow_link_warning
- used to turn off the warnings about having a slow cache link type. These warnings are thrown bydvc pull
anddvc checkout
when linking files takes longer than usual, to remind them that there are faster cache link types available than the defaults (reflink,copy
โ seecache.type
). Accepts valuestrue
andfalse
.These warnings are automatically turned off when
cache.type
is manually set. -
cache.shared
- permissions for newly created or downloaded cache files and directories. The only accepted value right now isgroup
, which makes DVC use664
(rw-rw-rโ) for files and775
(rwxrwxr-x) for directories. This is useful when sharing a cache among projects. The default permissions for cache files is system dependent. In Linux and macOS for example, they're determined usingos.umask
.
The following parameters allow setting an external cache location. A DVC remote name is used (instead of the URL) because often it's necessary to configure authentication or other connection settings, and configuring a remote is the way that can be done.
-
cache.local
- name of a local remote to use as external cache (refer todvc remote
for more info. on "local remotes".) This will overwrite the value incache.dir
(seedvc cache dir
). -
cache.s3
- name of an Amazon S3 remote to use as external cache. -
cache.gs
- name of a Google Cloud Storage remote to use as external cache. -
cache.ssh
- name of an SSH remote to use as external cache. -
cache.hdfs
- name of an HDFS remote to use as external cache. -
cache.webhdfs
- name of an HDFS remote with WebHDFS enabled to use as external cache.
โ ๏ธ Avoid using the same remote storage used for
dvc push
anddvc pull
as external cache, because it may cause file hash overlaps: the hash of an external output could collide with that of a local file with different content.
exp
Sets the default paths assumed by dvc exp init
. This can help avoid overriding
them repeatedly with that command's options, for example if all of your
experiments or projects use a similar structure.
-
exp.code
- path to your source file or directory dependency. -
exp.params
- path to your parameters file. -
exp.data
- path to your data file or directory dependency. -
exp.models
- path to your model/artifact(s) file or directory output. -
exp.metrics
- path to your metrics file output. -
exp.plots
- path to your plots file or directory output. -
exp.live
- path to your DVCLive output logs.
hydra
Sets the defaults for experiment configuration via Hydra Composition.
hydra.enabled
- enables Hydra config composition.hydra.config_dir
- location of the directory containing Hydra config groups. Defaults toconf
.hydra.config_name
- the name of the file containing the Hydra defaults list (located insidehydra.config_dir
). Defaults toconfig.yaml
.
parsing
-
parsing.bool
- Controls the templating syntax for boolean values when used in dictionary unpacking.Valid values are
"store_true"
(default) and"boolean_optional"
, named after Pythonargparse
actions.Given the following
params.yaml
:dict: bool-true: true bool-false: false
And corresponding
dvc.yaml
:stages: foo: cmd: python foo.py ${dict}
When using
store_true
,cmd
will be:python foo.py --bool-true
Whereas when using
boolean_optional
,cmd
will be:python foo.py --bool-true --no-bool-false
-
parsing.list
- Controls the templating syntax for list values when used in dictionary unpacking.Valid values are
"nargs"
(default) and"append"
, named after Pythonargparse
actions.Given the following
params.yaml
:dict: list: [1, 2, 'foo']
And corresponding
dvc.yaml
:stages: foo: cmd: python foo.py ${dict}
When using
nargs
,cmd
will be:python foo.py --list 1 2 'foo'
Whereas when using
append
,cmd
will be:python foo.py --list 1 --list 2 --list 'foo'
plots
-
plots.auto_open
- iftrue
, DVC will automatically open the HTML file generated bydvc plots
commands in a browser.false
by default -
plots.html_template
- sets a custom HTML template fordvc plots
. Accepts a path relative to the.dvc/
folder. -
plots.out_dir
- changes the default value fordvc plots show --out
anddvc plots diff --out
. The original default value isdvc_plots
.
state
-
state.row_limit
- maximum number of entries in state databases. This affects the physical size of the state files, as well as the performance of certain DVC operations. The default is 10,000,000 rows. The bigger the limit, the longer the file hash history that DVC can keep, for example. -
state.row_cleanup_quota
- percentage of the state database to be deleted when it reaches thestate.row_limit
. The default quota is 50%. DVC removes the oldest entries (created whendvc status
is used, for example). -
state.dir
- specify a custom location for the state databases (links/
andmd5/
directories), by default in.dvc/tmp
. This may be necessary when using DVC on NFS or other mounted volumes where SQLite encounters file permission errors.
index
index.dir
- specify a custom location for the directory where remote index files will be stored, by default in.dvc/tmp/index
. This may be necessary when using DVC on NFS or other mounted volumes.
Example: Add an S3 remote, and set it as default
๐ก Before adding an S3 remote, be sure to Create a Bucket.
$ dvc remote add myremote s3://bucket/path
$ dvc config core.remote myremote
Note that this is equivalent to using
dvc remote add
with the-d
/--default
flag.
Example: Default remotes
Use remote myremote
by default:
$ dvc config core.remote myremote
Get the default remote:
$ dvc config core.remote
myremote
Clear default remote value:
$ dvc config --unset core.remote
The above command is equivalent to:
$ dvc config core.remote -u
Example: Cache config options
Set the cache directory to an absolute path:
$ dvc config cache.dir /mnt/cache
$ dvc config cache.dir
/mnt/cache
or to a relative path (resolved from ./.dvc/
):
$ dvc config cache.dir ../../mycache
$ dvc pull
$ ls ../mycache
2f/
Set cache type: if reflink
is not available, use copy
:
$ dvc config cache.type reflink,copy