The configuration for the Software Heritage virtual file system resides in the swh > fuse section of the shared YAML configuration file used by all Software Heritage tools, located by default at ~/.config/swh/global.yml.

The configuration file location is subject to the XDG Base Directory specification as well as explicitly overridden on the command line via the -C/--config-file flag.

The following sub-sections and fields can be used within the swh > fuse stanza:

  • cache:

    • metadata: where to store the metadata cache, must have either a in-memory boolean entry or a path string entry (with the corresponding disk path)

    • blob: where to store the blob cache, same entries as the metadata cache

  • web-api:

    • url: archive API URL

    • auth-token: authentication token used with the API URL

If no configuration is given, default values are:

  • cache: all cache files are stored in $XDG_CACHE_HOME/swh/fuse/ (or ~/.cache/swh/fuse if XDG_CACHE_HOME is not set)

  • web-api: default URL is <>, with no authentication token


Here is a full ~/.config/swh/global.yml example, showcasing different cache storage strategies (in-memory for metadata and on-disk for blob), using the default Web API service:

        in-memory: true
        path: "/path/to/cache/blob.sqlite"
      url: ""
      auth-token: null