Install & Compatibility
Where this runs
tested against v2026.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.862s · 40.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.768s · 41MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SSHFileSystem
✓ from sshfs import SSHFileSystem
open
✓ from fsspec import open
Used for URL-based access, where 'ssh://' or 'sftp://' protocols are handled by sshfs.
This quickstart demonstrates how to connect to an SFTP server using `sshfs` with both password and SSH private key authentication. It shows direct usage of the `SSHFileSystem` class for programmatic file operations and integrates with `fsspec.open` for URL-based file access. It includes examples for listing, writing, and reading files, with cleanup operations. Remember to replace placeholder credentials with secure environment variables or a robust SSH configuration. [3, 10]
import os
from sshfs import SSHFileSystem
from fsspec import open
# Configuration (use environment variables for sensitive data)
SSH_HOST = os.environ.get('SSH_HOST', '127.0.0.1')
SSH_USER = os.environ.get('SSH_USER', 'user')
SSH_PASSWORD = os.environ.get('SSH_PASSWORD', 'password')
SSH_KEY_PATH = os.environ.get('SSH_KEY_PATH', '~/.ssh/id_rsa')
# --- Method 1: Using SSHFileSystem class directly ---
print("\n--- Using SSHFileSystem directly ---")
try:
# Connect with password
fs_pass = SSHFileSystem(SSH_HOST, username=SSH_USER, password=SSH_PASSWORD)
print(f"Connected to {SSH_HOST} with password. Current dir: {fs_pass.pwd()}")
# Example operation: list files
print("Files in remote home (password auth):", fs_pass.ls('.'))
fs_pass.close()
# Connect with private key
fs_key = SSHFileSystem(SSH_HOST, username=SSH_USER, client_keys=[SSH_KEY_PATH])
print(f"Connected to {SSH_HOST} with key. Current dir: {fs_key.pwd()}")
print("Files in remote home (key auth):", fs_key.ls('.'))
# Example: Write and read a file
remote_path = f'/tmp/test_sshfs_{os.getpid()}.txt'
with fs_key.open(remote_path, 'w') as f:
f.write('Hello from sshfs via key!')
with fs_key.open(remote_path, 'r') as f:
content = f.read()
print(f"Read from {remote_path}: '{content}'")
fs_key.rm(remote_path)
print(f"Cleaned up {remote_path}")
fs_key.close()
except Exception as e:
print(f"SSHFileSystem connection/operation failed: {e}")
# --- Method 2: Using fsspec.open with URL ---
print("\n--- Using fsspec.open with URL ---")
try:
# Using SSH URL with password
# Note: fsspec.open requires storage_options for auth. Password direct in URL is less secure.
# Better to pass via storage_options or rely on SSH agent/config.
with open(f'ssh://{SSH_USER}:{SSH_PASSWORD}@{SSH_HOST}/tmp/fsspec_test_{os.getpid()}.txt', 'w') as f:
f.write('Hello from fsspec.open!')
print("Wrote file via fsspec.open (password).")
with open(f'ssh://{SSH_USER}@{SSH_HOST}/tmp/fsspec_test_{os.getpid()}.txt', 'r',
client_keys=[SSH_KEY_PATH]) as f:
content = f.read()
print(f"Read via fsspec.open (key auth): '{content}'")
# Clean up (requires SSHFileSystem directly or a complex fsspec glob pattern)
fs_cleanup = SSHFileSystem(SSH_HOST, username=SSH_USER, client_keys=[SSH_KEY_PATH])
fs_cleanup.rm(f'/tmp/fsspec_test_{os.getpid()}.txt')
print("Cleaned up fsspec.open test file.")
fs_cleanup.close()
except Exception as e:
print(f"fsspec.open connection/operation failed: {e}")
print("\nQuickstart finished.")
Debug
Known issues
gotchaThere are two distinct Python libraries named 'sshfs' or related to SSH filesystems. This registry entry specifically pertains to `sshfs` (from `fsspec/sshfs` on GitHub), which is an `fsspec` implementation using `asyncssh`. Another library, `fs.sshfs` (from `althonos/fs.sshfs`), implements PyFilesystem2 using `paramiko`. Ensure you are installing and importing from the correct library for your needs.fixVerify your `pip install` command (`pip install sshfs` vs `pip install fs.sshfs`) and your import statements (`from sshfs import SSHFileSystem` vs `from fs.sshfs import SSHFS`). The current library is `sshfs` (asyncssh/fsspec). [3, 10, 7]
affects: All versions
gotchaAuthentication to the remote server requires careful handling of credentials. You must explicitly provide either a `password` or `client_keys` (a list of paths to private keys) when initializing `SSHFileSystem` or using `fsspec.open` with `storage_options`. Automatic detection of SSH agent or system-wide `~/.ssh/config` is not always guaranteed without explicit configuration or underlying library support. [3, 10]fixAlways pass `username` and either `password='your_password'` or `client_keys=['/path/to/id_rsa']` arguments. For `fsspec.open`, use the `storage_options` dictionary, e.g., `fsspec.open(..., storage_options={'username': 'user', 'client_keys': ['~/.ssh/id_rsa']})`. Avoid hardcoding sensitive credentials and prefer environment variables or a secure configuration management system. [3, 10] affects: All versions
breakingDeprecation of older SSH key algorithms (e.g., `ssh-rsa` with SHA1) in modern OpenSSH servers (v8.8+ onwards) can prevent connections if your client keys or the remote server's configuration still rely on them. While `asyncssh` (the backend for this `sshfs` library) generally supports modern algorithms, ensure your SSH keys are up-to-date (e.g., using ED25519 or RSA with SHA2-256/512). [15]fixGenerate new SSH keys using modern algorithms like `ssh-keygen -t ed25519` or `ssh-keygen -t rsa -b 4096 -o -a 100` and ensure your SSH server supports them. Consult your SSH server's `sshd_config` for allowed `HostKeyAlgorithms` and `PubkeyAcceptedAlgorithms`. Update `asyncssh` to the latest version to ensure it has the most current compatibility. [15]
affects: All versions when connecting to OpenSSH 8.8+ servers with outdated keys/configs
gotcha`sshfs` relies on `fsspec` and `asyncssh`. Breaking changes or compatibility issues in these underlying libraries, especially concerning API updates or security patches, can impact the functionality of `sshfs`. Regularly updating all dependencies is recommended, but be aware of potential breaking changes in major version bumps of `fsspec` or `asyncssh`.fixMonitor the release notes and changelogs for `fsspec` and `asyncssh` when performing updates. Test your `sshfs` integration thoroughly after updating dependencies to identify and address any compatibility issues. Use a `requirements.txt` or `pyproject.toml` to pin dependency versions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sshfs'
The 'sshfs' Python library is not installed in the current environment.
ModuleNotFoundError: No module named 'asyncssh'
The core dependency 'asyncssh' required by 'sshfs' is not installed.
asyncssh.exceptions.PermissionDenied
The provided credentials (username, password, or SSH key) are incorrect or lack permission to access the remote server.
fixVerify your username, password, or the path and passphrase for your SSH key are correct and authorized on the server.
asyncssh.exceptions.ConnectionRefusedError
The remote SSH server actively refused the connection, often due to the server being down, SSH service not running, or a firewall blocking the connection.
fixEnsure the remote SSH server is running, the SSH service is active, and no firewall is blocking the connection to the specified port.
Upgrade
Version history
2026.8.0latest on PyPI · released Aug 7, 2026
Audit
Dependencies
fsspecrequiredProvides the abstract filesystem interface that sshfs implements.
asyncsshrequiredUsed for secure SSH and SFTP communication.