{"id":9760,"library":"fs-sshfs","title":"fs-sshfs: PyFilesystem2 over SSH","description":"fs-sshfs is a PyFilesystem2 extension that allows you to treat a remote SSH server's filesystem as a local `fs.FS` object, leveraging Paramiko for SSH connectivity. The current version is 1.0.2, and it receives updates as needed, particularly for compatibility with its core `paramiko` dependency, ensuring robust and secure remote file access.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/althonos/fs.sshfs","tags":["filesystem","ssh","sftp","paramiko","remote-access","pyfilesystem2"],"install":[{"cmd":"pip install fs-sshfs","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Core dependency for SSH/SFTP client functionality.","package":"paramiko","optional":false}],"imports":[{"note":"The package is installed as 'fs-sshfs' but the top-level import is 'fs_sshfs' due to Python's module naming conventions.","wrong":"from fs.sshfs import SSHFS","symbol":"SSHFS","correct":"from fs_sshfs import SSHFS"}],"quickstart":{"code":"import os\nfrom fs_sshfs import SSHFS\nfrom paramiko import AutoAddPolicy\n\n# Set these environment variables or replace with actual values\n# For password authentication: export SSH_HOST='your_host' SSH_USER='your_user' SSH_PASSWORD='your_password'\n# For key-based authentication: export SSH_HOST='your_host' SSH_USER='your_user' SSH_PKEY_PATH='/path/to/your/key'\n\nhost = os.environ.get('SSH_HOST', '')\nuser = os.environ.get('SSH_USER', '')\npassword = os.environ.get('SSH_PASSWORD')\npkey_path = os.environ.get('SSH_PKEY_PATH')\nport = int(os.environ.get('SSH_PORT', 22))\n\nif not host or not user:\n    print(\"Please set SSH_HOST and SSH_USER environment variables.\")\n    exit(1)\n\n# Configure SSH key if path is provided\npkey = None\nif pkey_path:\n    try:\n        from paramiko import RSAKey, Ed25519Key, ECDSAKey, DSSKey\n        # Attempt to load common key types; more robust error handling might be needed\n        try: pkey = RSAKey.from_private_key_file(pkey_path) \n        except Exception: pass\n        try: pkey = Ed25519Key.from_private_key_file(pkey_path) \n        except Exception: pass\n        try: pkey = ECDSAKey.from_private_key_file(pkey_path) \n        except Exception: pass\n        try: pkey = DSSKey.from_private_key_file(pkey_path) \n        except Exception: pass\n\n        if not pkey: raise ValueError(\"Could not load PKEY from path\")\n        print(f\"Using SSH key from: {pkey_path}\")\n\n    except Exception as e:\n        print(f\"Warning: Could not load SSH key from {pkey_path}: {e}\")\n        print(\"Falling back to password or no authentication if key fails.\")\n        pkey = None\n\n\ntry:\n    with SSHFS(\n        host=host,\n        user=user,\n        passwd=password,\n        port=port,\n        pkey=pkey,\n        # AutoAddPolicy is convenient for development but insecure for production\n        missing_host_key_policy=AutoAddPolicy(),\n    ) as remote_fs:\n        print(f\"Successfully connected to {host} as {user}\")\n        print(\"Listing root directory of the remote filesystem:\")\n        \n        # Check if root is accessible and list contents\n        if remote_fs.exists('/'):\n            for info in remote_fs.scandir('/'):\n                print(f\"  {info.name} ({'directory' if info.is_dir else 'file'})\")\n        else:\n            print(\"  Root directory '/' does not exist or is inaccessible.\")\n\nexcept Exception as e:\n    print(f\"Error connecting or listing remote files: {e}\")\n    print(\"Please ensure SSH_HOST, SSH_USER, and either SSH_PASSWORD or SSH_PKEY_PATH are set correctly.\")\n    print(\"Also, verify the SSH server is running and accessible.\")","lang":"python","description":"This quickstart demonstrates how to connect to a remote SSH server using `fs-sshfs` and list the contents of its root directory. It uses environment variables for secure credential handling and includes `paramiko.AutoAddPolicy` for simplified host key management during development. For production, a more secure host key policy is recommended."},"warnings":[{"fix":"Upgrade `fs-sshfs` to version 1.0.2 or newer: `pip install --upgrade fs-sshfs`. Alternatively, pin your `paramiko` version to `<3.0` if `fs-sshfs` cannot be upgraded.","message":"Explicit support for Paramiko 3 was added in `fs-sshfs` v1.0.2. If you are using an older version of `fs-sshfs` (prior to 1.0.2) with `paramiko` v3.x, you may encounter compatibility issues or unexpected behavior due to API changes in Paramiko.","severity":"breaking","affected_versions":"<1.0.2"},{"fix":"Configure `missing_host_key_policy` in the `SSHFS` constructor. For development, `paramiko.AutoAddPolicy()` can be used (but is not recommended for production). For production, use `paramiko.WarningPolicy()` or `paramiko.RejectPolicy()` after pre-populating `~/.ssh/known_hosts`.","message":"SSH host key verification can prevent connections if the remote host's key is not present in the local `known_hosts` file or if a strict policy is configured, leading to `SSHException` errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `SSHFS` as a context manager (`with SSHFS(...) as remote_fs:`), which automatically calls `close()` upon exiting the `with` block. Alternatively, manually call `remote_fs.close()` when you are finished with the filesystem object.","message":"`fs-sshfs` instances establish and hold SSH connections. It is crucial to properly close these connections to release system resources, especially in long-running applications or when opening multiple connections.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify the SSH host and port are correct and the server is running and accessible from your client machine. Check network connectivity and local/remote firewall rules. Confirm the target host's SSH service is operational.","cause":"The SSH server is unreachable, the host or port is incorrect, or a firewall is blocking the connection.","error":"paramiko.ssh_exception.NoValidConnectionsError: Unable to connect to ..."},{"fix":"Double-check the `user`, `passwd`, or `pkey` arguments passed to `SSHFS`. Ensure the SSH key has the correct permissions (e.g., `chmod 400 keyfile.pem`) and is correctly loaded if using key-based authentication.","cause":"The provided username, password, or SSH key is incorrect or not authorized on the remote server.","error":"paramiko.ssh_exception.AuthenticationException: Authentication failed."},{"fix":"Set an appropriate `missing_host_key_policy` in the `SSHFS` constructor. For convenience during development, use `paramiko.AutoAddPolicy()`. For production, manually add the host's public key to your `~/.ssh/known_hosts` file, or implement a stricter policy like `paramiko.WarningPolicy()` or `paramiko.RejectPolicy()` after verifying the key.","cause":"The remote host's SSH key is unknown or has changed, and `paramiko`'s policy is set to reject unknown hosts.","error":"paramiko.ssh_exception.SSHException: Server '...' not found in known_hosts and not a host certificate."}]}