{"id":22384,"library":"snakemake-storage-plugin-fs","title":"Snakemake Storage Plugin FS","description":"A Snakemake storage plugin for reading and writing from a locally mounted filesystem using rsync. Version 1.1.3 is the latest stable release, with active development and monthly releases focused on bug fixes and compatibility with Snakemake's storage plugin API.","status":"active","version":"1.1.3","language":"python","source_language":"en","source_url":"https://github.com/snakemake/snakemake-storage-plugin-fs","tags":["snakemake","storage-plugin","filesystem","rsync","workflow-management"],"install":[{"cmd":"pip install snakemake-storage-plugin-fs","lang":"bash","label":"Standard install"}],"dependencies":[{"reason":"Plugin is loaded as a Snakemake storage plugin; requires Snakemake >=7.0.0","package":"snakemake","optional":false},{"reason":"Underlying tool for file transfer; not a Python dependency but must be installed on the system","package":"rsync","optional":true}],"imports":[{"note":"You need to import the class, not just the module. However, users typically never import this plugin manually; Snakemake discovers and uses it automatically.","wrong":"import snakemake_storage_plugin_fs","symbol":"StorageProviderFS","correct":"from snakemake_storage_plugin_fs import StorageProviderFS"}],"quickstart":{"code":"from snakemake_storage_plugin_fs import StorageProviderFS\n\n# Example: initialize with remote path and optional prefix\nprovider = StorageProviderFS(\n    remote_path=\"/path/to/remote\",\n    prefix=\"/local/prefix\"\n)\n\n# Example operations (normally triggered by Snakemake)\nprint(provider.list())\nprint(provider.stat(\"some_file.txt\"))","lang":"python","description":"Basic usage of the plugin to interact with a local filesystem storage. The plugin is typically used implicitly by Snakemake when a workflow references storage queries with 'fs://' prefix."},"warnings":[{"fix":"Install rsync (e.g., apt-get install rsync on Debian/Ubuntu, or brew install rsync on macOS).","message":"The plugin relies on rsync being installed on the system. Without it, file transfers will fail silently or with cryptic errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to v1.0.3 or later and remove any manual calls to deprecated validation methods.","message":"As of v1.0.3, the query validation API was deprecated. Old code that used `validate_query` directly will fail. Users should rely on Snakemake's standard query handling.","severity":"deprecated","affected_versions":"<=1.0.2"},{"fix":"Ensure the 'remote' path is actually a locally mounted directory (e.g., NFS, FUSE, or local disk). For remote SSH, use a different plugin (e.g., snakemake-storage-plugin-s3, snakemake-storage-plugin-gs).","message":"The plugin does not support remote hosts via SSH or any network protocol; it only works with locally mounted filesystems. Users may mistakenly try to use it with remote paths via SSH, which will fail because rsync is called without SSH flags by default.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to v1.1.3 or later, which explicitly passes `--links --no-perms --no-owner` to rsync to ensure symlinks are copied correctly.","message":"Symlinks are copied without preserving their targets by default in older versions. This can lead to broken symlinks in the cache.","severity":"gotcha","affected_versions":"<1.1.3"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Set the prefix in the Snakemake configuration file (e.g., config.yaml) using the key 'storage-fs-prefix' or via the environment variable 'SNAKEMAKE_STORAGE_FS_PREFIX'.","cause":"User passed --storage-prefix directly to Snakemake command line, but the plugin expects the prefix to be set via config file or environment variable.","error":"snakemake: error: unrecognized arguments: --storage-prefix"},{"fix":"Run 'pip install snakemake-storage-plugin-fs' in the correct Python environment (e.g., conda environment or virtualenv).","cause":"The plugin is not installed, or the environment is misconfigured.","error":"ModuleNotFoundError: No module named 'snakemake_storage_plugin_fs'"},{"fix":"Install rsync via your package manager (e.g., 'apt-get install rsync' or 'brew install rsync').","cause":"rsync is not installed on the system.","error":"rsync: command not found"},{"fix":"Mount the remote filesystem locally (e.g., via sshfs) and use the local mount point as the remote_path.","cause":"User attempted to use the plugin with a remote SSH path, but the plugin does not support SSH authentication.","error":"Permission denied (publickey)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}