Common Options

Metadata related options {#mount-metadata-options}

Items	Description
--subdir=value	mount a sub-directory as root (default: "")
--backup-meta=3600	interval (in seconds) to automatically backup metadata in the object storage (0 means disable backup) (default: "3600")
--backup-skip-trash <VersionAdd>1.2</VersionAdd>	skip files and directories in trash when backup metadata.
--heartbeat=12	interval (in seconds) to send heartbeat; it's recommended that all clients use the same heartbeat value (default: "12")
--read-only	Read-only mode, i.e. allow only lookup/read operations. Note that this option implies --no-bgjob, so read-only clients do not execute background jobs.
--no-bgjob	Disable background jobs, default to false, which means clients by default carry out background jobs, including:

<ul><li>Clean up expired files in Trash (look for `cleanupDeletedFiles`, `cleanupTrash` in [`pkg/meta/base.go`](https://github.com/juicedata/juicefs/blob/main/pkg/meta/base.go))</li><li>Delete slices that's not referenced (look for `cleanupSlices` in [`pkg/meta/base.go`](https://github.com/juicedata/juicefs/blob/main/pkg/meta/base.go))</li><li>Clean up stale client sessions (look for `CleanStaleSessions` in [`pkg/meta/base.go`](https://github.com/juicedata/juicefs/blob/main/pkg/meta/base.go))</li></ul>Note that compaction isn't affected by this option, it happens automatically with file reads and writes, client will check if compaction is in need, and run in background (take Redis for example, look for `compactChunk` in [`pkg/meta/base.go`](https://github.com/juicedata/juicefs/blob/main/pkg/meta/redis.go)).| |`--atime-mode=noatime` <VersionAdd>1.1</VersionAdd> |Control atime (last time the file was accessed) behavior, support the following modes: <ul><li>`noatime` (default): set when the file is created or when `SetAttr` is explicitly called. Accessing and modifying the file will not affect atime, tracking atime comes at a performance cost, so this is the default behavior</li><li>`relatime`: update inode access times relative to mtime (last time when the file data was modified) or ctime (last time when file metadata was changed). Only update atime if atime was earlier than the current mtime or ctime, or the file's atime is more than 1 day old</li><li>`strictatime`: always update atime on access</li></ul>| |`--skip-dir-nlink=20` <VersionAdd>1.1</VersionAdd> |number of retries after which the update of directory nlink will be skipped (used for tkv only, 0 means never) (default: 20)| |`--skip-dir-mtime=100ms` <VersionAdd>1.2</VersionAdd>|skip updating attribute of a directory if the mtime difference is smaller than this value (default: 100ms)| |`--sort-dir` <VersionAdd>1.3</VersionAdd>|sort entries within a directory by name| |`--fast-statfs` <VersionAdd>1.3</VersionAdd>|performance of `statfs` is improved by using local caching to reduce metadata access, but accuracy may decrease (default: false)|

Metadata cache related options {#mount-metadata-cache-options}

For metadata cache description and usage, refer to Kernel metadata cache and Client memory metadata cache.

Items	Description
--attr-cache=1	attributes cache timeout in seconds (default: 1), read Kernel metadata cache
--entry-cache=1	file entry cache timeout in seconds (default: 1), read Kernel metadata cache
--dir-entry-cache=1	dir entry cache timeout in seconds (default: 1), read Kernel metadata cache
--open-cache=0	open file cache timeout in seconds (0 means disable this feature) (default: 0)
--open-cache-limit value <VersionAdd>1.1</VersionAdd>	max number of open files to cache (soft limit, 0 means unlimited) (default: 10000)
--readdir-cache=false <VersionAdd>1.3, only for mount</VersionAdd>	enable directory entry cache (default: false, disable this feature)
--negative-entry-cache=0 <VersionAdd>1.3, only for mount</VersionAdd>	negative lookup (return ENOENT) cache timeout in seconds (default: 0, means disable this feature)

Data storage related options {#mount-data-storage-options}

Items	Description
--storage=file	Object storage type (e.g. s3, gs, oss, cos) (default: "file", refer to documentation for all supported object storage types).
--bucket=value	customized endpoint to access object storage
--storage-class value <VersionAdd>1.1</VersionAdd>	the storage class for data written by current client
--get-timeout=60	the max number of seconds to download an object (default: 60)
--put-timeout=60	the max number of seconds to upload an object (default: 60)
--io-retries=10	The number of retries when the network is abnormal and the number of retries for metadata requests are also controlled by this option. If the number of retries is exceeded, an EIO Input/output error error will be returned. (default: 10)
--max-uploads=20	Upload concurrency, defaults to 20. This is already a reasonably high value for 4M writes, with such write pattern, increasing upload concurrency usually demands higher --buffer-size, learn more at Read/Write Buffer. But for random writes around 100K, 20 might not be enough and can cause congestion at high load, consider using a larger upload concurrency, or try to consolidate small writes in the application end.
--max-stage-write=0 <VersionAdd>1.2</VersionAdd>	The maximum number of concurrent writes of data blocks to the cache disk asynchronously. If the maximum number of concurrent writes is reached, the object storage will be uploaded directly (this option is only valid when "Client write data cache" is enabled) (default value: 0, that is, no concurrency limit)
--max-deletes=10	number of threads to delete objects (default: 10)
--upload-limit=0	bandwidth limit for upload in Mbps (default: 0)
--download-limit=0	bandwidth limit for download in Mbps (default: 0)
--check-storage<VersionAdd>1.3</VersionAdd>	test storage before mounting to expose access issues early

Data cache related options {#mount-data-cache-options}

Items	Description
--buffer-size=300	total read/write buffering in MiB (default: 300), see Read/Write buffer
--prefetch=1	prefetch N blocks in parallel (default: 1), see Client read data cache
--writeback	upload objects in background (default: false), see Client write data cache
--upload-delay=0	When --writeback is enabled, you can use this option to add a delay to object storage upload, default to 0, meaning that upload will begin immediately after write. Different units are supported, including s (second), m (minute), h (hour). If files are deleted during this delay, upload will be skipped entirely, when using JuiceFS for temporary storage, use this option to reduce resource usage. Refer to Client write data cache.
--upload-hours <VersionAdd>1.2</VersionAdd>	When --writeback is enabled, data blocks are only uploaded during the specified time of day. The format of the parameter is <start hour>,<end hour> (including "start hour", but not including "end hour", "start hour" must be less than or greater than "end hour"), where <hour> can range from 0 to 23. For example, 0,6 means that data blocks are only uploaded between 0:00 and 5:59 every day, and 23,3 means that data blocks are only uploaded between 23:00 every day and 2:59 the next day.
--cache-dir=value	directory paths of local cache, use : (Linux, macOS) or ; (Windows) to separate multiple paths (default: $HOME/.juicefs/cache or /var/jfsCache), see Client read data cache
--cache-mode value <VersionAdd>1.1</VersionAdd>	file permissions for cached blocks (default: "0600")
--cache-size=102400	size of cached object for read in MiB (default: 102400), see Client read data cache
--cache-items=0 <VersionAdd>1.3</VersionAdd>	max number of cached items (default is 0, which will be automatically calculated based on the free‑space‑ratio.)
--free-space-ratio=0.1	min free space ratio (default: 0.1), if Client write data cache is enabled, this option also controls write cache size, see Client read data cache
--cache-partial-only	cache random/small read only (default: false), see Client read data cache
--cache-large-write <VersionAdd>1.3</VersionAdd>	cache full blocks after uploading
--verify-cache-checksum=extend <VersionAdd>1.1</VersionAdd>	Checksum level for cache data. After enabled, checksum will be calculated on divided parts of the cache blocks and stored on disks, which are used for verification during reads. The following strategies are supported:

<ul><li>`none`: Disable checksum verification, if local cache data is tampered, bad data will be read;</li><li>`full` (default before 1.3): Perform verification when reading the full block, use this for sequential read scenarios;</li><li>`shrink`: Perform verification on parts that's fully included within the read range, use this for random read scenarios;</li><li>`extend`: Perform verification on parts that fully include the read range, this causes read amplifications and is only used for random read scenarios demanding absolute data integrity. (default since 1.3)</li></ul>| |`--cache-eviction=2-random` <VersionAdd>1.1</VersionAdd> |cache eviction policy (`none` or `2-random`) (default: "2-random")| |`--cache-scan-interval=1h` <VersionAdd>1.1</VersionAdd> |interval (in seconds) to scan cache-dir to rebuild in-memory index (default: "1h")| |`--cache-expire=0` <VersionAdd>1.2</VersionAdd>|Cache blocks that have not been accessed for more than the set time, in seconds, will be automatically cleared (even if the value of `--cache-eviction` is `none`, these cache blocks will be deleted). A value of 0 means never expires (default: 0)| |`--max-readahead` <VersionAdd>1.3</VersionAdd>|max buffering for read ahead in MiB|

Metrics related options {#mount-metrics-options}

||Items|Description| |-|-| |--metrics=127.0.0.1:9567|address to export metrics (default: 127.0.0.1:9567)| |--custom-labels|custom labels for metrics, format: key1:value1;key2:value2 (default: "")| |--consul=127.0.0.1:8500|Consul address to register (default: 127.0.0.1:8500)| |--no-usage-report|do not send usage report (default: false)|

Windows related options {#mount-windows-options}

Items	Description
--o=	Used to specify additional FUSE mount options. The actual supported options are determined by WinFsp.
--log=c:/juicefs.log <VersionAdd>1.3</VersionAdd>	Path to save JuiceFS logs (only effective when running in background mode).
-d <VersionAdd>1.3</VersionAdd>	Run in background mode. On Windows, enabling this will run JuiceFS as a system service. (Note: This requires administrator privileges and only one file system can be mounted at a time in this mode.)
--fuse-trace-log=c:/fuse.log <VersionAdd>1.3</VersionAdd>	Specifies the trace log path for WinFsp's FUSE layer callbacks. (Default: "")
--as-root	A compatibility option that maps all file uid, gid, and write operations to the root user (uid=0).
--show-dot-files <VersionAdd>1.3</VersionAdd>	Show files that begin with a dot (.). By default, such files are treated as hidden.
--winfsp-threads=16 <VersionAdd>1.3</VersionAdd>	Sets the number of threads WinFsp uses to handle kernel events. The default is min(CPU cores * 2, 16).
--report-case <VersionAdd>1.3</VersionAdd>	Configures whether JuiceFS should report the precise case of filenames when possible. For example, when opening aaa.txt that actually exists as AAA.txt, enabling this option allows JuiceFS to report the original case to the Windows kernel. (Note: Enabling this may affect performance.)