{"id":2785,"library":"sshfs","title":"SSH Filesystem for fsspec","description":"sshfs is an implementation of fsspec, providing a unified Pythonic interface for interacting with SFTP servers over SSH. It leverages the asyncssh library for its underlying secure shell operations, offering a fast and asynchronous way to manage remote filesystems. The library is actively maintained, with its current version being 2025.11.0, and typically sees several releases per year to incorporate updates and improvements. [3, 10]","status":"active","version":"2025.11.0","language":"en","source_language":"en","source_url":"https://github.com/fsspec/sshfs","tags":["ssh","sftp","filesystem","fsspec","async","remote","file-transfer"],"install":[{"cmd":"pip install sshfs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the abstract filesystem interface that sshfs implements.","package":"fsspec","optional":false},{"reason":"Used for secure SSH and SFTP communication.","package":"asyncssh","optional":false}],"imports":[{"symbol":"SSHFileSystem","correct":"from sshfs import SSHFileSystem"},{"note":"Used for URL-based access, where 'ssh://' or 'sftp://' protocols are handled by sshfs.","symbol":"open","correct":"from fsspec import open"}],"quickstart":{"code":"import os\nfrom sshfs import SSHFileSystem\nfrom fsspec import open\n\n# Configuration (use environment variables for sensitive data)\nSSH_HOST = os.environ.get('SSH_HOST', '127.0.0.1')\nSSH_USER = os.environ.get('SSH_USER', 'user')\nSSH_PASSWORD = os.environ.get('SSH_PASSWORD', 'password')\nSSH_KEY_PATH = os.environ.get('SSH_KEY_PATH', '~/.ssh/id_rsa')\n\n# --- Method 1: Using SSHFileSystem class directly ---\nprint(\"\\n--- Using SSHFileSystem directly ---\")\ntry:\n    # Connect with password\n    fs_pass = SSHFileSystem(SSH_HOST, username=SSH_USER, password=SSH_PASSWORD)\n    print(f\"Connected to {SSH_HOST} with password. Current dir: {fs_pass.pwd()}\")\n    # Example operation: list files\n    print(\"Files in remote home (password auth):\", fs_pass.ls('.'))\n    fs_pass.close()\n\n    # Connect with private key\n    fs_key = SSHFileSystem(SSH_HOST, username=SSH_USER, client_keys=[SSH_KEY_PATH])\n    print(f\"Connected to {SSH_HOST} with key. Current dir: {fs_key.pwd()}\")\n    print(\"Files in remote home (key auth):\", fs_key.ls('.'))\n\n    # Example: Write and read a file\n    remote_path = f'/tmp/test_sshfs_{os.getpid()}.txt'\n    with fs_key.open(remote_path, 'w') as f:\n        f.write('Hello from sshfs via key!')\n    with fs_key.open(remote_path, 'r') as f:\n        content = f.read()\n    print(f\"Read from {remote_path}: '{content}'\")\n    fs_key.rm(remote_path)\n    print(f\"Cleaned up {remote_path}\")\n    fs_key.close()\n\nexcept Exception as e:\n    print(f\"SSHFileSystem connection/operation failed: {e}\")\n\n# --- Method 2: Using fsspec.open with URL ---\nprint(\"\\n--- Using fsspec.open with URL ---\")\ntry:\n    # Using SSH URL with password\n    # Note: fsspec.open requires storage_options for auth. Password direct in URL is less secure.\n    # Better to pass via storage_options or rely on SSH agent/config.\n    with open(f'ssh://{SSH_USER}:{SSH_PASSWORD}@{SSH_HOST}/tmp/fsspec_test_{os.getpid()}.txt', 'w') as f:\n        f.write('Hello from fsspec.open!')\n    print(\"Wrote file via fsspec.open (password).\")\n\n    with open(f'ssh://{SSH_USER}@{SSH_HOST}/tmp/fsspec_test_{os.getpid()}.txt', 'r',\n              client_keys=[SSH_KEY_PATH]) as f:\n        content = f.read()\n    print(f\"Read via fsspec.open (key auth): '{content}'\")\n\n    # Clean up (requires SSHFileSystem directly or a complex fsspec glob pattern)\n    fs_cleanup = SSHFileSystem(SSH_HOST, username=SSH_USER, client_keys=[SSH_KEY_PATH])\n    fs_cleanup.rm(f'/tmp/fsspec_test_{os.getpid()}.txt')\n    print(\"Cleaned up fsspec.open test file.\")\n    fs_cleanup.close()\n\nexcept Exception as e:\n    print(f\"fsspec.open connection/operation failed: {e}\")\n\nprint(\"\\nQuickstart finished.\")","lang":"python","description":"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]"},"warnings":[{"fix":"Verify 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]","message":"There 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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]","message":"Authentication 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]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Generate 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]","message":"Deprecation 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]","severity":"breaking","affected_versions":"All versions when connecting to OpenSSH 8.8+ servers with outdated keys/configs"},{"fix":"Monitor 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.","message":"`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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}