Cloud Storage FUSE configuration file

This document describes how to use a Cloud Storage FUSE configuration file toconfigure the behavior ofCloud Storage FUSE in a persistent manner. To use theconfiguration file, specify the path to the configuration file in the--config-file option when you run thegcsfuse command.

The Cloud Storage FUSE configuration file is a YAML file that uses the followingformat and fields. Behavior controlled by the configuration file fields canalso be set using theCloud Storage FUSE CLI.

Note: For specific high-performance machine types, some fields are automaticallyset to specific values by default to maximize performance. Values that aremanually set at the time of mount will override these defaults. For moreinformation, seeAutomated configuration values for high-performance machine types.

Cloud Storage FUSE configuration file format and fields

The following YAML configuration example shows the format and fieldsavailable in Cloud Storage FUSE.

app-name:"APP_NAME"logging: file-path:"FILE_PATH" format:FORMAT severity:SEVERITYlog-rotate:max-file-size-mb:MAX_FILE_SIZEbackup-file-count:BACKUP_FILE_COUNTcompress:COMPRESScache-dir:"CACHE_DIR"file-cache:max-size-mb:MAX_SIZEcache-file-for-range-read:CACHE_FILE_FOR_RANGE_READenable-parallel-downloads:ENABLE_PARALLEL_DOWNLOADSparallel-downloads-per-file:PARALLEL_DOWNLOADS_PER_FILEmax-parallel-downloads:MAX_PARALLEL_DOWNLOADSdownload-chunk-size-mb:DOWNLOAD_CHUNK_SIZEmetadata-cache:enable-nonexistent-type-cache:ENABLE_NONEXISTENT_TYPE_CACHEnegative-ttl-secs:ENABLE_NEGATIVE_TTL_SECSstat-cache-max-size-mb:STAT_CACHE_MAX_SIZEttl-secs:TTL_SECStype-cache-max-size-mb:TYPE_CACHE_MAX_SIZEonly-dir:"ONLY_DIR"gcs-auth:anonymous-access:ANONYMOUS_ACCESSkey-file:"KEY_FILE"reuse-token-from-url:REUSE_TOKEN_FROM_URLtoken-url:"TOKEN_URL"gcs-connection:billing-project:"BILLING_PROJECT"client-protocol:CLIENT_PROTOCOLcustom-endpoint:"CUSTOM_ENDPOINT"http-client-timeout:HTTP_CLIENT_TIMEOUTlimit-bytes-per-sec:"LIMIT_BYTES_PER_SEC"limit-ops-per-sec:"LIMIT_OPS_PER_SEC"max-conns-per-host:MAX_CONNS_PER_HOSTmax-idle-conns-per-host:MAX_IDLE_CONNS_PER_HOSTsequential-read-size-mb:SEQUENTIAL_READ_SIZEimplicit-dirs:IMPLICIT_DIRSfile-system:kernel-list-cache-ttl-secs:KERNEL_LIST_CACHE_TTL_SECSignore-interrupts:IGNORE_INTERRUPTSdir-mode:"DIR_MODE"file-mode:"FILE_MODE"fuse-options:FUSE_OPTIONSgid:GIDrename-dir-limit:RENAME_DIR_LIMITtemp-dir:"TEMP_DIR"uid:UIDforeground:FOREGROUNDgcs-retries:max-retry-attempts:MAX_RETRY_ATTEMPTSmax-retry-sleep:MAX_RETRY_SLEEPmultiplier:"MULTIPLIER"metrics:cloud-metrics-export-interval-secs:CLOUD_METRICS_EXPORT_INTERVALprometheus-port:PROMETHEUS_PORTdebug:log-mutex:LOG_MUTEXexit-on-invariant-violation:EXIT_ON_INVARIANT_VIOLATIONwrite:enable-streaming-writes:STREAMING_WRITESglobal-max-blocks:MAXIMUM_GLOBAL_BLOCKSread:enable-buffered-read:ENABLE_BUFFERED_READglobal-max-blocks:MAXIMUM_GLOBAL_READ_BLOCKSprofile:PROFILE

Cloud Storage FUSE configuration file fields

The following table describes the fields you can specify in your Cloud Storage FUSEconfiguration file. Unless stated otherwise, all fields are optional.

FieldDescriptionValid valueDefault value

app-name

The application name of the mount.String value, for example:"my-bucket-mount".""

file-path

The path to the log file where logs will be written. If this field is unspecified, the logs are routed tostdout when Cloud Storage FUSE runs in foreground mode and tosyslogs when Cloud Storage FUSE runs in background mode.String value, for example:"/var/log".""

format

Specifies the format of the log file.
  • text
  • json
json

severity

The severity level you want Cloud Storage FUSE to generate logs for. The severity levels are ordered from lowest severity to highest severity. For example, when you specifywarning, Cloud Storage FUSE generates logs for warnings and errors. Generally, we recommend using theinfo severity level.

Note: If you specify--debug_mutex as part of your command, the severity level is automatically set totrace and overrideslog-severity.Note: Using either thetrace ordebug severity levels when file caching is enabled can result in performance degradation due to logging overhead and should only be used temporarily such as during troubleshooting.
  • off: disables all logging.
  • error: contains messages about serious issues that prevent Cloud Storage FUSE from completing an operation, or indicate a failure such as mount failures, permission errors, and critical input/output (I/O) errors.
  • warning: contains messages indicating potential issues that aren't critical but can lead to issues if not addressed. Potential issues include non-fatal connection issues, deprecation warnings, resource contention that might cause slight performance degradation, and retries for transient failures. This severity level also includes information provided in theerror severity level.
  • info: contains logging information such as startup and shutdown messages, or information about successful mount operations, progress updates, and configuration settings. This severity level also includes information about thewarning anderror severity levels.
  • debug: contains logging information such as startup and shutdown messages, or information about successful mount operations, progress updates, and configuration settings. This severity level also includes the information provided in theinfo,warning, anderror severity levels.
  • trace: contains granular details about each Cloud Storage FUSE operation and function call, outlining thegcsfuse interaction with the kernel FUSE driver and Cloud Storage. This severity level also includes the details provided indebug,info,warning, anderror severity levels.
info

max-file-size-mb

The maximum size in megabytes (MB) that log files can reach before being rotated.Integer. The minimum value is1.512

backup-file-count

The maximum number of rotated log files to retain, excluding the active file that logs are written to.
  • Integer
  • 0: Retains all rotated log files
10

compress

Specifies whether rotated log files are compressed usinggzip.Boolean value:true,falsetrue

cache-dir

Enables thefile cache and specifies the directory for storing file cache data.

Note: The Cloud Storage FUSE CSI driver for Google Kubernetes Engine uses a different method to enable file caching. To learn how to enable file caching on Google Kubernetes Engine, seeFile caching in Cloud Storage FUSE.		A path, for example:"/tmp/gcsfuse-cache-path". An empty value indicates this field is disabled. This field is disabled by default.

max-size-mb

Specifies the maximum size in MiB that thefile cache can use and lets you limit the total capacity the file cache can use within its mounted directory.

Note: Before you set thefile-cache:max-size-mb field, you must first specify thecache-dir field. For Compute Engine VMs (including standalone Cloud Storage FUSE or non-Google Kubernetes Engine based deployments), enablingcache-dir automatically setsfile-cache:max-size-mb to-1.
  • Integer
  • -1: Specifies the use of the cache's entire available capacity in the directory you specify forcache-dir. This is the default only ifcache-dir is passed.
  • 0: Disables the file cache.
-1

cache-file-for-range-read

Determines whether the full object should be downloaded asynchronously and stored in the Cloud Storage FUSE cache directory when the first read is completed from a non-zero offset. This field should be set totrue if you plan to perform several random reads or partial reads.Note: If you perform a partial read starting at offset0, Cloud Storage FUSE asynchronously downloads and caches the full object.Boolean value:true,falsefalse

enable-parallel-downloads

Accelerates reads of large files by using the file cache directory as a prefetch buffer using multiple workers to download multiple parts of a file in parallel.

Parallel downloads are automatically enabled when you enable file caching. To learn more about file caching, seeUse Cloud Storage FUSE file caching.

To learn more about parallel downloads and how to configure supporting properties,Parallel downloads.

Boolean value:true,false.true

parallel-downloads-per-file

Specifies the number of maximum goroutines to spawn per file to download the object from Cloud Storage into the file cache.Integer16

max-parallel-downloads

The maximum number of goroutines that can be spawned at any given time across all the download jobs of files.
  • Integer
  • -1: Specifies unlimited parallel downloads.
  • 0: Disables parallel downloads. Can only be used if--enable-parallel-downloads is not passed or is passed asfalse.
Twice the number of CPU cores on your machine or16, whichever is higher.

download-chunk-size-mb

Specifies the size of each read request in MiB that eachgoroutine makes to Cloud Storage when downloading the object into the file cache.Integer200

enable-nonexistent-type-cache

Creates atype cache entry with the typeNonexistentType if a file isn't found in Cloud Storage. If the file gets created in Cloud Storage but theNonexistentType entry for the file is cached, then Cloud Storage FUSE cannot request that file until theNonexistentType entry is removed from the type cache.Boolean value:true,falsefalse

stat-cache-max-size-mb

The maximum size memory that thestat cache can use, in MiB. The stat cache is always entirely kept in memory.
  • Integer. We recommend the following:
    • 32 if your workload involves up to 20,000 files.
    • If your workload is larger than 20,000 files, increase the size by values of 10 for every additional 6,000 files, where the stat cache uses an average of 1,500 MiB per file.
  • -1: Sets no limit, where the stat cache use as much memory as needed.
  • 0: Disables the stat cache.
32

negative-ttl-secs

Defines the time to live (TTL) in seconds ofnegative stat cache entries, which store results for non-existent files in the cache.

  • Integer representing seconds, for example:10 (10 seconds).
  • 0: Disables negative stat caching.
  • -1: Allows unlimited negative stat caching and disables a TTL expiration.
5

ttl-secs

Defines the time to live (TTL) in seconds of cached metadata entries.
  • Integer representing seconds, for example:30 (30 seconds).
  • -1: Bypass TTL expiration and serve files from the cache whenever they're available.
  • 0: Use the most up-to-date file. Using this value issues aGet metadata call to make sure that the object generation for the file in the cache matches what's stored in Cloud Storage.
60

type-cache-max-size-mb

The maximum size in MiB per directory that thetype cache can use. The type cache is always entirely kept in memory.
  • Integer. We recommend the following:
    • 4 if the maximum number of files within a single directory from the bucket you're mounting contains 20,000 files or less.
    • If the maximum number of files within a single directory that you're mounting contains more than 20,000 files, increase the value by1 for every 5,000 files, which is an average of around 200 bytes per file.
  • -1: Specifies no limit and lets the type cache use as much memory as needed.
  • 0: Disables the type cache.
4

only-dir

Mounts only a specific directory within a bucket.A path, for example:"/etc/gcsfuse.yaml".

anonymous-access

Disables authentication for requests. This field should be set if you're using a custom endpoint that doesn't support authentication. This field should also be set if you're using Cloud Storage FUSE with public buckets.Boolean value:true,falsefalse

key-file

Specifies an absolute path to the credential JSON key file for authenticating requests to Cloud Storage. By default, Cloud Storage FUSE usesApplication Default Credentials to authenticate requests.A URL.When this field is not set, Application Default Credentials are used.

reuse-token-from-url

Specifies whether to reuse the token acquired from--token-url.Boolean value:true,falsetrue

token-url

Specifies a URL for getting an access token when the--key-file is absent.A URL.

billing-project

Specifies a project to use for billing when the mounted bucket is accessed. This field isoften required when mounting a bucket enabled withRequester Pays.String value representing a"project ID".""

client-protocol

Specifies the protocol used for communicating with the Cloud Storage backend.http1

custom-endpoint

Specifies an alternative custom endpoint for fetching data. The custom endpoint must support the equivalent resources and operations as the Cloud Storage JSON endpoint,storage.UNIVERSE_DOMAIN_NAME:443. If a custom endpoint isn't specified, Cloud Storage FUSE uses the global Cloud Storage JSON API endpoint,storage.googleapis.com:443. If authentication isn't supported on the custom endpoint you specify, set theanonymous-access field totrue to bypass authentication.An endpoint, for example:storage.googleapis.com:443.

http-client-timeout

Specifies how long the Cloud Storage FUSE HTTP client can wait to get a response from the server before timing out.Duration, for example:1h10m10s for 1 hour, 10 minutes, and 10 seconds.0s specifies no timeout.0s, which specifies no timeout

limit-bytes-per-sec

Specifies the bandwidth limit at which Cloud Storage FUSE can read data from Cloud Storage, measured over a 30-second window."-1", which specifies no limit.

limit-ops-per-sec

Specifies a limit for operations performed per second, measured over a 30-second window.Floating point number.-1 specifies no limit."-1"

max-conns-per-host

Specifies the maximum number of TCP connections allowed per server. This becomes effective when--client-protocol is set tohttp1.0

max-idle-conns-per-host

Specifies the maximum number of idle connections allowed per server. This becomes effective when--client-protocol is set tohttp1.Integer between0 and2147483647.0 specifies no limit on TCP connections.0

sequential-read-size-mb

Specifies the chunk size of the data to be downloaded from Cloud Storage, in megabytes (MB).Integer between1 and1024.200

implicit-dirs

Implicitly includesfolders andmanaged folders. SeeFiles and directories in the Cloud Storage FUSE GitHub documentation for more information.Boolean value:true,falsefalse

kernel-list-cache-ttl-secs

Enables thelist cache and defines the time to live (TTL) in seconds of cached list entries. The list cache is kept in memory in the page cache, which is controlled by the kernel based on available memory.

Note: Recommended for read-only mounts to avoid consistency issues. For more information, see theperformance tuning best practices for list caching.
  • Integer representing seconds, for example:10 (10 seconds).
  • 0: Disables list caching.
  • -1: Bypasses entry expiration and always returns the list response from the cache when it's available.
0

ignore-interrupts

Instructs Cloud Storage FUSE to ignore system interrupt signals, like SIGINT triggered byControl+C. This prevents signals from terminating in-flight operations.Boolean value:true,false.true

dir-mode

Permissions bits for directories, in octal.Integer between000 and777 (inclusive)."755"

file-mode

Specifies permissions bits for files, in octal.Integer between000 and777 (inclusive)."644"

fuse-options

Specifies additional system-specific mount options.

gid

Specifies the Group Identifier (GID) owner of all inodes.
  • Integer representing a GID.
  • -1: The GID of the caller is used.
-1

rename-dir-limit

Allows the renaming of directories containing fewer descendants than the specified limit.Integer between0 and2147483647.0

temp-dir

Specifies a path to the temporary directory where writes are staged prior to being uploaded to Cloud Storage.A string path, for example:"/mnt/ssd/example-user-gcsfuse-temp-dir"."/tmp"

uid

Specifies the User Identifier (UID) owner of all inodes.
  • Integer representing a UID.
  • -1: The UID of the caller is used.
-1

foreground

Runs thegcsfuse command in the foreground.Boolean value:true,falsefalse

max-retry-attempts

Specifies the maximum number of times an operation is retried if the operation fails, preventing endless retry loops.
  • Integer representing the maximum number of retry attempts, for example:10.
  • 0: Allows unlimited retry attempts.
0

max-retry-sleep

Specifies the maximum duration that Cloud Storage FUSE is allowed to sleep in a retry loop withexponential backoff. Once the backoff duration exceeds the specified maximum duration, the retry continues with the specified maximum duration.Duration, for example:1h5m50s (1 hour, 5 minutes, and 50 seconds) or60s (60 seconds).30s

multiplier

Specifies the multiplier for exponential backoff between consecutive retries.Floating-point number"2"

cloud-metrics-export-interval-secs

Exports metrics to Cloud Monitoring with the specified interval.

Note: Using this field requires additional setup. For more information, seeSet up the Cloud Monitoring exporter.		Integer representing a value in seconds, for example:10 (10 seconds).0 specifies no exporting.0

prometheus-port

Exposes Prometheus metrics endpoint on the specified port and/metrics path.

Note: Using this field requires additional setup. For more information, seeSet up the Prometheus exporter.		Integer representing the port you want to specify.0

log-mutex

Prints debug messages when a mutex is held too long. If this field is specified, the severity level of logs is automatically set totrace, which includes trace logs, debug logs, info logs, warning logs, and error logs.Boolean value:true,false.false

exit-on-invariant-violation

Exits the program when internal variant violations are detected.Boolean value:true,false.false

enable-streaming-writes

Controls the write path flow so that data is uploaded directly to Cloud Storage as its written instead of fully staging the write locally and uploading it uponclose() orfsync(). For more information about streaming writes, seeReads/Writes in the Cloud Storage FUSE GitHub documentation.Boolean value:true,false.true

write:global-max-blocks

Specifies the maximum number of data chunks available for streaming writes across all files. Each file uses one 32 MiB data chunk by default.

  • Integer
  • 0: disables streaming writes.
  • -1: sets the value to unlimited chunks.
  • Default value for low-specification machines with limited resources:4
  • Default value for high-specification machines with a large amount of resources:1600

enable-buffered-read

Specifies asynchronous prefetching of parts of a Cloud Storage object into an in-memory buffer, allowing subsequent reads to be served from the buffer instead of requiring network calls.Boolean value:true,falsefalse

read:global-max-blocks

Specifies the maximum number of blocks available for buffered reads across all file handles.

Note: Using this field requires enabling theenabled-buffered-read field. For more information, see theenable-buffered-read field.
  • Integer
  • 0: disables buffered reads.
  • -1: sets the value to unlimited blocks.
40

profile

Applies a predefined, optimized set of Cloud Storage FUSE configurations for caching, threading, and buffer sizes to help you achieve high performance for a specific workload type, such as training, serving, and checkpointing. To learn more about each predefined configuration based on your workload type, seeProfile-based configurations for AI/ML workloads.
  • A string, for example,"aiml-checkpointing".
  • "aiml-training": optimizes performance for high throughput reads of large datasets and prevents Cloud GPUs and Cloud TPU hardware from waiting for data.
  • aiml-checkpointing: optimizes performance for high throughput writes for large files by drastically reducing the time it takes to save multi-gigabyte checkpoints, minimizing training pauses.
  • aiml-serving: optimizes performance for serving workloads by streamlining data access and applying caching mechanisms.
""

Back to top

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.