dvc remote

Set up and manage data remotes

Description

DVC remote commands help you configure and manage remote storage locations where DVC stores cached data and model files. Remotes can be cloud storage (S3, GCS, Azure), network storage (SSH, HDFS), or local directories.

Subcommands

remote add

Add a new data remote.

S3 Remote

dvc remote add myremote s3://mybucket/path

Arguments

name · string · required

Name of the remote (converted to lowercase).

url · string · required

Remote location. Supported URLs include:

• s3://bucket/path - Amazon S3
• gs://bucket/path - Google Cloud Storage
• azure://container/path - Azure Blob Storage
• ssh://user@host/path - SSH/SFTP
• hdfs://namenode/path - HDFS
• /local/path - Local directory
• http://example.com/path - HTTP

See full list of supported URLs.

Options

-d, --default · flag

Set as default remote.

-f, --force · flag

Force overwriting existing configs.

--global · flag

Use global config (~/.config/dvc/config).

--system · flag

Use system config.

--project · flag

Use project config (.dvc/config).

--local · flag

Use local config (.dvc/config.local).

---

remote default

Set/unset the default data remote.

Set Default Remote

dvc remote default myremote

Arguments

name · string

Name of the remote to set as default. Omit to show current default.

Options

-u, --unset · flag

Unset default remote.

--global · flag

Use global config.

--system · flag

Use system config.

--project · flag

Use project config.

--local · flag

Use local config.

---

remote list

List all available data remotes.

dvc remote list

Example Output

myremote    s3://mybucket/path    (default)
backup      gs://backup-bucket/dvc-storage
local       /mnt/shared/dvc-cache

The default remote is highlighted in green and marked with “(default)“.

---

remote modify

Modify the configuration of a data remote.

AWS Credentials

dvc remote modify myremote access_key_id AKIAIOSFODNN7EXAMPLE
dvc remote modify myremote secret_access_key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Arguments

name · string · required

Name of the remote.

option · string · required

Name of the option to modify. Common options:

• access_key_id, secret_access_key - AWS credentials
• region - AWS region
• profile - AWS profile name
• endpointurl - Custom endpoint URL
• ssl_verify - Enable/disable SSL verification
• url - Change remote URL

value · string

Value of the option. Omit when using --unset.

Options

-u, --unset · flag

Unset option.

--global · flag

Use global config.

--system · flag

Use system config.

--project · flag

Use project config.

--local · flag

Use local config.

---

remote remove

Remove a data remote.

dvc remote remove myremote

Arguments

name · string · required

Name of the remote to remove.

Options

--global · flag

Use global config.

--system · flag

Use system config.

--project · flag

Use project config.

--local · flag

Use local config.

---

remote rename

Rename a DVC remote.

dvc remote rename oldname newname

Arguments

name · string · required

Remote to be renamed.

new · string · required

New name of the remote.

Options

--global · flag

Use global config.

--system · flag

Use system config.

--project · flag

Use project config.

--local · flag

Use local config.

Examples

Setting Up AWS S3 Remote

# Add S3 remote
dvc remote add -d storage s3://my-bucket/dvc-storage

# Configure AWS credentials (stored in .dvc/config.local)
dvc remote modify --local storage access_key_id AKIAIOSFODNN7EXAMPLE
dvc remote modify --local storage secret_access_key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Set region
dvc remote modify storage region us-east-1

# Push data to remote
dvc push

Store credentials in .dvc/config.local (not tracked by Git) using --local flag for security.

Setting Up Google Cloud Storage

# Add GCS remote
dvc remote add -d storage gs://my-bucket/dvc-storage

# Configure using service account
dvc remote modify storage credentialpath credentials.json

# Or use default application credentials
dvc remote modify storage credentialpath ''

Multiple Remotes for Different Purposes

# Production remote
dvc remote add prod s3://prod-bucket/dvc-cache
dvc remote default prod

# Staging remote
dvc remote add staging s3://staging-bucket/dvc-cache

# Local backup
dvc remote add backup /mnt/backup/dvc-storage

# Push to specific remote
dvc push -r staging

SSH Remote with Key Authentication

# Add SSH remote
dvc remote add storage ssh://[e-mail]/data/dvc-storage

# Configure SSH key
dvc remote modify storage keyfile ~/.ssh/id_rsa

# Set custom port
dvc remote modify storage port 2222

Supported Storage Types

Amazon S3

AWS S3 and S3-compatible storage (MinIO, DigitalOcean Spaces)

Google Cloud Storage

GCS buckets with service account or default credentials

Azure Blob Storage

Azure containers with connection string or SAS token

SSH/SFTP

Remote servers via SSH with key or password authentication

HDFS

Hadoop Distributed File System

HTTP/HTTPS

Read-only HTTP servers (for pulling data)

Local Directory

Network-mounted directories or local paths

WebDAV

WebDAV protocol (Nextcloud, ownCloud)

Configuration Levels

DVC supports four configuration levels (in order of precedence):

1. Local (.dvc/config.local)

   Machine-specific settings, not tracked by Git. Use for credentials.

2. Project (.dvc/config)

   Project-wide settings, tracked by Git. Use for remote URLs.

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

   User-wide settings across all projects.

4. System (/etc/dvc/config)

   System-wide settings for all users.

Security Best Practice: Never commit credentials to Git. Always use --local flag when setting sensitive options like access_key_id or password.

Common Remote Options

AWS S3 Options

• access_key_id - AWS access key
• secret_access_key - AWS secret key
• region - AWS region (e.g., us-east-1)
• profile - AWS CLI profile name
• endpoint_url - Custom S3 endpoint
• ssl_verify - Enable/disable SSL verification

Google Cloud Storage Options

• credentialpath - Path to service account JSON file
• projectname - GCP project name

Azure Options

• connection_string - Azure storage connection string
• account_name - Storage account name
• sas_token - Shared Access Signature token

SSH Options

• keyfile - Path to SSH private key
• password - SSH password
• port - SSH port (default: 22)
• timeout - Connection timeout

Related Commands

• dvc push - Upload data to remote storage
• dvc pull - Download data from remote storage
• dvc fetch - Download data to cache without checkout
• dvc config - Direct configuration management