dvc-ssh

4.2.2 verified Mon Apr 27 auth: no python

SSH plugin for DVC (Data Version Control) that enables remote storage on SSH servers. Current version 4.2.2, requires Python >=3.9. Active development with regular releases.

pip install dvc-ssh

Common errors

error ModuleNotFoundError: No module named 'dvc_ssh' ↓

cause Trying to import dvc-ssh directly as a Python module.

fix

dvc-ssh is a plug-in, not a Python package to import. Install it with 'pip install dvc-ssh' and use DVC's API from the 'dvc' module (e.g., from dvc import DVC).

error ERROR: failed to add remote - unknown remote type 'ssh' ↓

cause dvc-ssh is not installed or not compatible with the current DVC version.

fix

Install dvc-ssh with 'pip install dvc-ssh' and ensure DVC version >=3.0.

error asyncssh.errors.HostKeyNotVerifiable: No matching host key for server ↓

cause SSH host key verification failed because the host key is unknown or changed.

fix

Use asyncssh's known_hosts configuration or set the environment variable 'ASYNCSSH_KNOWN_HOSTS' to point to a known_hosts file. Alternatively, disable host key checking (not recommended): add 'StrictHostKeyChecking no' to SSH config or set 'DVC_SSH_STRICT_HOST_KEY_CHECK=false'.

error Remote 'myremote' is not a DVC remote ↓

cause The remote URL is not properly configured or the path is invalid.

fix

Ensure the SSH URL is in format 'ssh://user@host:port/path'. Use 'dvc remote list' to verify, and 'dvc remote modify' to update.

Warnings

breaking Version 4.0.0 replaced dvc_objects.callbacks with fsspec.callbacks. Custom callback implementations must be updated. ↓

fix Replace any imports from dvc_objects.callbacks with from fsspec.callbacks and update callback usage accordingly.

deprecated Version 3.0.0 drops support for DVC 2.x. Ensure DVC version is >=3.0.0. ↓

fix Upgrade DVC to version 3.x or later.

gotcha SSH configuration (host key verification, auth methods) is handled by asyncssh. Default behavior may prompt for passwords interactively. ↓

fix Set up passwordless SSH keys or configure asyncssh options via dvc config or environment variables.

gotcha File transfer uses atomic write by default since v4.2.2, which may fail on some filesystems with limited permissions. ↓

fix If atomic writes cause issues, you can set DVC_NO_ATOMIC_WRITE=1 environment variable or adjust remote permissions.

Install

pip install dvc[ssh]

Imports

DVC
wrong
```
from dvc_ssh import DVC
```
correct
```
from dvc import DVC
```
dvc-ssh is a plugin, not a standalone package. Import DVC from dvc.
RemoteLOCAL
wrong
```
from dvc_ssh import SSHFileSystem
```
correct
```
from dvc.fs import SSHFileSystem
```
The filesystem class is provided by dvc, not dvc-ssh.

Quickstart

Initialize DVC repo with SSH remote. Run inside a git repository.

import os
from dvc import DVC
from dvc.repo import Repo

# Initialize DVC repository (in existing git repo)
repo = Repo.init()

# Add remote SSH storage
ssh_url = f"ssh://{os.environ.get('SSH_USER', 'user')}@{os.environ.get('SSH_HOST', 'example.com')}:{os.environ.get('SSH_PORT', '22')}{os.environ.get('SSH_PATH', '/path/to/storage')}"
repo.add_remote(name='myremote', url=ssh_url, default=False)

# Print configured remotes
print(repo.config['remote'])