OS Manuals

/usr/bin/gcsfuse

A user-space file system for interacting with Google Cloud Storage

From gcsfuse 2.12.2-r41 (os), captured 2026-11-10 by running gcsfuse --help (exit 0). permalink

Also provided by 1 other package version
Cloud Storage FUSE is an open source FUSE adapter that lets you mount
and access Cloud Storage buckets as local file systems. For a technical overview
of Cloud Storage FUSE, see https://cloud.google.com/storage/docs/gcs-fuse.

Usage:
  gcsfuse [flags] bucket mount_point

Flags:
      --anonymous-access                             This flag disables authentication.
      --app-name string                              The application name of this mount.
      --billing-project string                       Project to use for billing when accessing a bucket enabled with "Requester Pays".
      --cache-dir string                             Enables file-caching. Specifies the directory to use for file-cache.
      --client-protocol string                       The protocol used for communicating with the GCS backend. Value can be 'http1' (HTTP/1.1), 'http2' (HTTP/2) or 'grpc'. (default "http1")
      --cloud-metrics-export-interval-secs int       Specifies the interval at which the metrics are uploaded to cloud monitoring
      --config-file string                           The path to the config file where all gcsfuse related config needs to be specified. Refer to 'https://cloud.google.com/storage/docs/gcsfuse-cli#config-file' for possible configurations.
      --create-empty-file                            For a new file, it creates an empty file in Cloud Storage bucket as a hold.
      --custom-endpoint string                       Specifies an alternative custom endpoint for fetching data. The custom endpoint must support the equivalent resources and operations as the GCS JSON endpoint, https://storage.googleapis.com/storage/v1. If a custom endpoint is not specified, GCSFuse uses the global GCS JSON API endpoint, https://storage.googleapis.com/storage/v1.
      --debug_invariants                             Exit when internal invariants are violated.
      --debug_mutex                                  Print debug messages when a mutex is held too long.
      --dir-mode string                              Permissions bits for directories, in octal. (default "0755")
      --enable-nonexistent-type-cache                Once set, if an inode is not found in GCS, a type cache entry with type NonexistentType will be created. This also means new file/dir created might not be seen. For example, if this flag is set, and metadata-cache-ttl-secs is set, then if we create the same file/node in the meantime using the same mount, since we are not refreshing the cache, it will still return nil.
      --enable-streaming-writes                      Enables streaming uploads during write file operation.
      --file-cache-cache-file-for-range-read         Whether to cache file for range reads.
      --file-cache-download-chunk-size-mb int        Size of chunks in MiB that each concurrent request downloads. (default 200)
      --file-cache-enable-parallel-downloads         Enable parallel downloads.
      --file-cache-max-parallel-downloads int        Sets an uber limit of number of concurrent file download requests that are made across all files. (default 128)
      --file-cache-max-size-mb int                   Maximum size of the file-cache in MiBs (default -1)
      --file-cache-parallel-downloads-per-file int   Number of concurrent download requests per file. (default 16)
      --file-mode string                             Permissions bits for files, in octal. (default "0644")
      --foreground                                   Stay in the foreground after mounting.
      --gid int                                      GID owner of all inodes. (default -1)
  -h, --help                                         help for gcsfuse
      --http-client-timeout duration                 The time duration that http client will wait to get response from the server. A value of 0 indicates no timeout.
      --ignore-interrupts                            Instructs gcsfuse to ignore system interrupt signals (like SIGINT, triggered by Ctrl+C). This prevents those signals from immediately terminating gcsfuse inflight operations. (default true)
      --implicit-dirs                                Implicitly define directories based on content. See files and directories in docs/semantics for more information
      --kernel-list-cache-ttl-secs int               How long the directory listing (output of ls <dir>) should be cached in the kernel page cache. If a particular directory cache entry is kept by kernel for longer than TTL, then it will be sent for invalidation by gcsfuse on next opendir (comes in the start, as part of next listing) call. 0 means no caching. Use -1 to cache for lifetime (no ttl). Negative value other than -1 will throw error.
      --key-file string                              Absolute path to JSON key file for use with GCS. If this flag is left unset, Google application default credentials are used.
      --limit-bytes-per-sec float                    Bandwidth limit for reading data, measured over a 30-second window. (use -1 for no limit) (default -1)
      --limit-ops-per-sec float                      Operations per second limit, measured over a 30-second window (use -1 for no limit) (default -1)
      --log-file string                              The file for storing logs that can be parsed by fluentd. When not provided, plain text logs are printed to stdout when Cloud Storage FUSE is run  in the foreground, or to syslog when Cloud Storage FUSE is run in the  background.
      --log-format string                            The format of the log file: 'text' or 'json'. (default "json")
      --log-rotate-backup-file-count int             The maximum number of backup log files to retain after they have been rotated. A value of 0 indicates all backup files are retained. (default 10)
      --log-rotate-compress                          Controls whether the rotated log files should be compressed using gzip. (default true)
      --log-rotate-max-file-size-mb int              The maximum size in megabytes that a log file can reach before it is rotated. (default 512)
      --log-severity string                          Specifies the logging severity expressed as one of [trace, debug, info, warning, error, off] (default "info")
      --max-conns-per-host int                       The max number of TCP connections allowed per server. This is effective when client-protocol is set to 'http1'. A value of 0 indicates no limit on TCP connections (limited by the machine specifications).
      --max-idle-conns-per-host int                  The number of maximum idle connections allowed per server. (default 100)
      --max-retry-attempts int                       It sets a limit on the number of times an operation will be retried if it fails, preventing endless retry loops. A value of 0 indicates no limit.
      --max-retry-sleep duration                     The maximum duration allowed to sleep in a retry loop with exponential backoff for failed requests to GCS backend. Once the backoff duration exceeds this limit, the retry continues with this specified maximum value. (default 30s)
      --metadata-cache-negative-ttl-secs int         The negative-ttl-secs value in seconds to be used for expiring negative entries in metadata-cache. It can be set to -1 for no-ttl, 0 for no cache and > 0 for ttl-controlled negative entries in metadata-cache. Any value set below -1 will throw an error. (default 5)
      --metadata-cache-ttl-secs int                  The ttl value in seconds to be used for expiring items in metadata-cache. It can be set to -1 for no-ttl, 0 for no cache and > 0 for ttl-controlled metadata-cache. Any value set below -1 will throw an error. (default 60)
      --o strings                                    Additional system-specific mount options. Multiple options can be passed as comma separated. For readonly, use --o ro
      --only-dir string                              Mount only a specific directory within the bucket. See docs/mounting for more information
      --prometheus-port int                          Expose Prometheus metrics endpoint on this port and a path of /metrics.
      --rename-dir-limit int                         Allow rename a directory containing fewer descendants than this limit.
      --retry-multiplier float                       Param for exponential backoff algorithm, which is used to increase waiting time b/w two consecutive retries. (default 2)
      --reuse-token-from-url                         If false, the token acquired from token-url is not reused. (default true)
      --sequential-read-size-mb int                  File chunk size to read from GCS in one call. Need to specify the value in MB. ChunkSize less than 1MB is not supported (default 200)
      --stat-cache-max-size-mb int                   The maximum size of stat-cache in MiBs. It can also be set to -1 for no-size-limit, 0 for no cache. Values below -1 are not supported. (default 32)
      --temp-dir string                              Path to the temporary directory where writes are staged prior to upload to Cloud Storage. (default: system default, likely /tmp)
      --token-url string                             A url for getting an access token when the key-file is absent.
      --type-cache-max-size-mb int                   Max size of type-cache maps which are maintained at a per-directory level. (default 4)
      --uid int                                      UID owner of all inodes. (default -1)
  -v, --version                                      version for gcsfuse
Options (56)
OptionDescriptionSource
--anonymous-accessThis flag disables authentication.help
--app-name stringThe application name of this mount.help
--billing-project stringProject to use for billing when accessing a bucket enabled with "Requester Pays".help
--cache-dir stringEnables file-caching.help
--client-protocol stringThe protocol used for communicating with the GCS backend.help
--cloud-metrics-export-interval-secs intSpecifies the interval at which the metrics are uploaded to cloud monitoringhelp
--config-file stringThe path to the config file where all gcsfuse related config needs to be specified.help
--create-empty-fileFor a new file, it creates an empty file in Cloud Storage bucket as a hold.help
--custom-endpoint stringSpecifies an alternative custom endpoint for fetching data.help
--debug_invariantsExit when internal invariants are violated.help
--debug_mutexPrint debug messages when a mutex is held too long.help
--dir-mode stringPermissions bits for directories, in octal.help
--enable-nonexistent-type-cacheOnce set, if an inode is not found in GCS, a type cache entry with type NonexistentType will be created.help
--enable-streaming-writesEnables streaming uploads during write file operation.help
--file-cache-cache-file-for-range-readWhether to cache file for range reads.help
--file-cache-download-chunk-size-mb intSize of chunks in MiB that each concurrent request downloads.help
--file-cache-enable-parallel-downloadsEnable parallel downloads.help
--file-cache-max-parallel-downloads intSets an uber limit of number of concurrent file download requests that are made across all files.help
--file-cache-max-size-mb intMaximum size of the file-cache in MiBs (default -1)help
--file-cache-parallel-downloads-per-file intNumber of concurrent download requests per file.help
--file-mode stringPermissions bits for files, in octal.help
--foregroundStay in the foreground after mounting.help
--gid intGID owner of all inodes.help
-h, --helphelp for gcsfusehelp
--http-client-timeout durationThe time duration that http client will wait to get response from the server.help
--ignore-interruptsInstructs gcsfuse to ignore system interrupt signals (like SIGINT, triggered by Ctrl+C).help
--implicit-dirsImplicitly define directories based on content.help
--kernel-list-cache-ttl-secs intHow long the directory listing (output of ls <dir>) should be cached in the kernel page cache.help
--key-file stringAbsolute path to JSON key file for use with GCS.help
--limit-bytes-per-sec floatBandwidth limit for reading data, measured over a 30-second window.help
--limit-ops-per-sec floatOperations per second limit, measured over a 30-second window (use -1 for no limit) (default -1)help
--log-file stringThe file for storing logs that can be parsed by fluentd.help
--log-format stringThe format of the log file: 'text' or 'json'.help
--log-rotate-backup-file-count intThe maximum number of backup log files to retain after they have been rotated.help
--log-rotate-compressControls whether the rotated log files should be compressed using gzip.help
--log-rotate-max-file-size-mb intThe maximum size in megabytes that a log file can reach before it is rotated.help
--log-severity stringSpecifies the logging severity expressed as one of [trace, debug, info, warning, error, off] (default "info")help
--max-conns-per-host intThe max number of TCP connections allowed per server.help
--max-idle-conns-per-host intThe number of maximum idle connections allowed per server.help
--max-retry-attempts intIt sets a limit on the number of times an operation will be retried if it fails, preventing endless retry loops.help
--max-retry-sleep durationThe maximum duration allowed to sleep in a retry loop with exponential backoff for failed requests to GCS backend.help
--metadata-cache-negative-ttl-secs intThe negative-ttl-secs value in seconds to be used for expiring negative entries in metadata-cache.help
--metadata-cache-ttl-secs intThe ttl value in seconds to be used for expiring items in metadata-cache.help
--o stringsAdditional system-specific mount options.help
--only-dir stringMount only a specific directory within the bucket.help
--prometheus-port intExpose Prometheus metrics endpoint on this port and a path of /metrics.help
--rename-dir-limit intAllow rename a directory containing fewer descendants than this limit.help
--retry-multiplier floatParam for exponential backoff algorithm, which is used to increase waiting time b/w two consecutive retries.help
--reuse-token-from-urlIf false, the token acquired from token-url is not reused.help
--sequential-read-size-mb intFile chunk size to read from GCS in one call.help
--stat-cache-max-size-mb intThe maximum size of stat-cache in MiBs.help
--temp-dir stringPath to the temporary directory where writes are staged prior to upload to Cloud Storage.help
--token-url stringA url for getting an access token when the key-file is absent.help
--type-cache-max-size-mb intMax size of type-cache maps which are maintained at a per-directory level.help
--uid intUID owner of all inodes.help
-v, --versionversion for gcsfusehelp

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.