Command Reference

JuiceFS provides many commands to help you manage your file system. This page provides a detailed reference for these commands.

Overview

If you run juicefs by itself, it will print all the available subcommands. In addition, you can add -h/--help flag after each subcommand to get help information of that subcommand.

juicefs COMMAND [options]

COMMAND could be:
  auth      authorize a filesystem
  mount     mount a filesystem
  umount    umount a filesystem
  info      show information of file or directory
  lsof      list recent opened files
  import    import files from existing object storage
  rmr       remove all files/directories recursively
  snapshot  create or remove snapshots
  grep      parallelized file pattern searcher
  profile   analyze log (Experimental)
  benchmark run benchmark
  doctor    collect diagnose information
  warmup    build cache for target directories/files
  version   show the version

Usage: juicefs [COMMAND] [options]

Add -h or --help after all commands, getting arguments list and help information.

juicefs auth

Authenticate the client against JuiceFS Console, and fetch or update configuration file for the JuiceFS Volume, and stored in $HOME/.juicefs/$VOL_NAME.conf. This command is useful when you need to deploy JuiceFS via script, or use self-hosted object storage for onpremise deployment.

Synopsis

juicefs auth NAME [options]

Options

Items	Description
NAME	The name of your file system.
--token=TOKEN	The JuiceFS token of your file system, you can find this token in the web console.
--bucket=BUCKET	name or endpoint of the bucket (optional)
--access-key=ACCESSKEY	The access key of your bucket, you can read our guide on how to get access key and secret from your service provider.
--secret-key=SECRETKEY	The secret key of your bucket, you can read our guide on how to get access key and secret from your service provider.
--session-token=SESSIONTOKEN	the session token to access the bucket (optional)
--bucket2=BUCKET2	name or endpoint of the secondary bucket (optional)
--access-key2=ACCESSKEY2	When data replication is enabled, use this parameter to specify the access key for the secondary bucket. Learn more at Cross-region data replication.
--secret-key2=SECRETKEY2	When data replication is enabled, use this parameter to specify the secret key for the secondary bucket. Learn more at Cross-region data replication.
--session-token2=SESSION_TOKEN2	the session token to access the bucket (optional)
--passphrase=PASSPHRASE	Passphrase for encrypted key, see Data Encryption for more.
--subdir=SUBDIR	Specify a sub-directory for mount, you can also create ACL to restrict client access to specific sub-directories, learn more at Client Access Control
--conf-dir=CONFDIR	a directory for configuration (default: /root/.juicefs)
--no-update	Client will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior, and then client will no longer talk to JuiceFS Console when mounting.

Notes

1. You will be prompted to enter the access key and secret if you didn't provide it through the --token, --accesskey and --secretkey options.
2. If your object storage provider allows accessing without key pairs (e.g. AWS IAM), you can leave blank when you are asked for access and secret keys, or you can simply pass an empty string to the --accesskey and --secretkey options.

juicefs mount

Mount the file system. You must provide the token of the file system (check the "File System Settings" in the website console), and the key pair to access the object storage (refer to How to Get Object Storage Access Key and Secret Key for details).

If the configuration file is not generated by the auth subcommand before mounting the file system, the client will ask you to provide the file system token and the key pair to access the object storage API separately through command line interaction.

You can mount JuiceFS as root or normal user, but due to permission issues, cache and client log locations will be different, read option descriptions below for more.

Synopsis

juicefs mount NAME MOUNTPOINT [options]

Options

Items	Description
NAME	The name of your file system.
MOUNTPOINT	The mount point for your file system.
--update-fstab	add or update entry in /etc/fstab, when applicable, see Auto-mount on boot.
-f, --foreground	Run in the foreground mode, client logs will print directly to console, often used in debugging.
-b, --background	Run in the background mode, which is the default behavior.
--subdir=SUBDIR	Specify a sub-directory for mount, you can also create ACL to restrict client access to specific sub-directories, learn more at Client Access Control
--ioretries=IORETRIES	(default: 30) number of retries for network failure
--http=ADDRESS	The bind address to serve files using HTTP, for example, localhost:8080.
--disallow-list	Disallow list a directory in WebDAV
--log=LOGPATH	Log file location, defaults to /var/log/juicefs.log (when running as root) or ~/.juicefs/log/juicefs.log (when running as normal user).
-v, --verbose	Print verbose log.
--no-update	Client will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior, and then client will no longer talk to JuiceFS Console when mounting.

Object Storage Options

Items	Description
--external	Prefer to use the external entrypoint of the object storage service. This means the traffic of JuiceFS will go through the public network instead of the internal network.
--internal	Prefer to use the internal entrypoint of the object storage service. This means the traffic of JuiceFS will go through the internal network instead of the public network. (Applicable to some object storages that separate internal and external network domain names, e.g. Aliyun OSS, UCloud UFile, etc.)
--max-uploads=MAXUPLOADS	Max number of concurrent uploads (default: 20), increasing upload concurrency usually demands higher --buffer-size, learn more at Read/Write Buffer.
--prefetch=PREFETCH	When a block is randomly read by a small offset range, the whole block is scheduled for download asynchronously, this is called prefetch in JuiceFS. This parameter controls the number of prefetch concurrency (default: 1), set to 0 to disable this behavior. In some situation, prefetch causes read amplification, see read amplification.
--upload-limit=UPLOADLIMIT	Maximum bandwidth for upload in Mbps, default to 0 (unlimited). Apart from bandwidth control, this parameter can also be used for system load control with high throughput scenarios.
--download-limit=DOWNLOADLIMIT	Maximum bandwidth for download in Mbps, default to 0 (unlimited). Apart from bandwidth control, this parameter can also be used for system load control with high throughput scenarios.
--delete-limit=DELETELIMIT	Maximum QPS for deletion default to 0 (unlimited). Use this if for example, some object storage limit API calls.
--get-timeout=GETTIMEOUT	Max number of seconds to get an object (default: 60), may need to increase this in low bandwidth conditions, see Read / Write error.
--put-timeout=PUTTIMEOUT	Max number of seconds to upload an object (default: 60), may need to increase this in low bandwidth conditions, see Read / Write error.
--gc	After mount, check for object storage garbage (unreferenced objects) and delete them. We do not expect JuiceFS to produce leak in object storage, but if there's relevant suspicions, run gc to check and cleanup.
--dry	Only check for garbage in object storage when running gc, but do not delete them.
--flip	When data replication is enabled, use secondary bucket as primary bucket. Learn more at Cross-region data replication.

Security Options

Items	Description
--rsa-key=RSAKEY	Path to RSA private key (PEM). Passphrase will be asked or provided with JFS_RSA_PASSPHRASE environment variable.

Cache Options

Read Cache to understand JuiceFS's cache design.

Items	Description
--cache-dir=CACHEDIR	Cache directory, defaults to /var/jfsCache (when running as root) or $HOME/.juicefs/cache (when running as normal user). Separate multiple directories by :, add quotation mark if using wildcard match (*). e.g. --cache-dir '/data*/jfsCache:/mydata*/jfsCache'
--cache-size=CACHESIZE	Local cache size limit in MiB, default to 102400 (100GiB). When multiple directories are used as cache directory, --cache-size limits the total size sum (split evenly).
--free-space-ratio=FREESPACE	Minimum free space ratio on cache disk (default: 0.2), if Client write cache is enabled, this option also controls write cache size
--buffer-size=BUFFERSIZE	the total size of memory used for read/write buffering in MiB (default: 300), learn more at Read/Write Buffer
--cache-mode=CACHEMODE	file permission for cached blocks (default: 0600)
--cache-group=CACHEGROUP	the name of group to join and provide remote cache (default: no sharing)
--subgroups=SUBGROUPS	the number of sub-groups in a cache group (default: 0)
--group-ip=GROUPIP	set IP address for cache group, usually this is only needed when you must manually specify network interface in a multi-NIC node
--no-sharing	(default: false) do not share cached blocks to others
--writeback	(default: false) data will be written to local disk first, and be uploaded to object storage asynchronously in the background.
--cache-partial-only	(default: false) If only cache the blocks for small reads
--fill-group-cache	build remote cache for new written blocks
--metacache	Enable metadata caching in local memory.
--metacacheto=METACACHETO	(default: 300) Expiration of the meta cache (seconds).
--max-cached-inodes=MAXCACHEDINODES	(default: 5000000) the max number of cached inodes
--opencache	Open a file for read using cached metadata, default to false, which means every open operation access metadata service to check for file changes. If file is frequently opened and scarcely changed, consider enabling --opencache to further improve read performance.
--attrcacheto=ATTRCACHETO	File attribute cache timeout in seconds, default to 1.
--entrycacheto=ENTRYCACHETO	File entry cache timeout in seconds, default to 1.
--direntrycacheto=DIRENTRYCACHETO	Directory entry cache timeout in seconds (default: 1).
--readdir-cache	cache readdir in kernel (require Linux kernel 4.20+)

FUSE Options

Items	Description
--allow-other	Allow accesses from other users. This option is enabled by default when you are running as root user. You need to enable this feature explicitly otherwise.
--enable-xattr	Enable extended attributes (xattr) support, default to false, which is recommended for most scenarios because xattr comes with its own overhead.
--enable-acl	Enable POSIX ACL support.
--no-posix-lock	Disable POSIX lock support.
--no-bsd-lock	Disable BSD lock support.
--block-interrupt=BLOCKINTERRUPT	(default: 1) number of seconds to block interruption
-o FUSE_OPTS	Other FUSE options. For example, enabling FUSE write cache through -o writeback_cache can greatly improve the performance of random writes and fragmented writes (requires Linux Kernel 3.15 and above).

See how to mount a file system in the document Getting Started.

Experimental Options

Items	Description
--min-balance-diff=MINBALANCEDIFF	When the inodes difference between the current zone and the zone with the least inodes exceeds this value, the metadata will be automatically balanced.
--min-dir-inodes=MINDIRINODES	When the number of directories in the current path exceeds this value, the metadata is automatically balanced.
--max-space=MAXSPACE	limit the total space in GiB (default: no limit)
--source=SOURCE	Use JuiceFS as cache for a directory
--refresh-interval=REFRESHINTERVAL	checking for update (seconds)
--update-source	propagate all changes to source
--fsck	check consistency

Deprecated Options

The follow options have been deprecated by JuiceFS, only reserved for reference.

Items	Description
--async	see --writeback
--ssl	Use HTTPS to access object store (always enabled)
--dircache	see --metacache
-d	see -v
--cacheDir=CACHEDIR	see --cache-dir
--cacheSize=CACHESIZE	see --cache-size
--allow-root	allow root to access (use --allow-other instead)
--no-sync	do not sync the replicated object store
--batch=BATCH	number of seconds to wait to combine multiple small files as single object
--keep-fd	keep FUSE session alive

juicefs umount

Umount a JuiceFS file system. This command handles the platform differences, i.e. umount in Linux and diskutil unmount in macOS.

Synopsis

juicefs umount PATH [options]

Options

Items	Description
PATH	The mount point for your file system.
-f --force	Umount it forcibly.

juicefs info

Show information about the file or directory stored in JuiceFS.

Synopsis

juicefs info PATH [options]

Options

Items	Description
PATH	The path to the file you are querying.
-n --plain	Show sizes in bytes.

Examples

Show information of a directory.

$ juicefs info /jfs/logs
/jfs/logs:
 inodes:      4      # inode total
  directories:    2      # directory total
  files:      2      # file total
 chunks:      44     # chunk total of all files
 length:      2.91G  # real size of all files
 size:            2.91G  # billable size, every file and directory is aligned to 4KB as minimum billable size

Show information of a file.

$ juicefs info --plain /jfs/daily-log.tar
/jfs/daily-log.tar:
 inode:   2955        # inode ID of the file
 length:  3128903680  # real size of the file
 size:    3128950784    # billable size, minimum is 4KB
 chunks:  47          # chunk total and detail, maximum 64MB for each chunk
   0: 58597 67108864 0 67108864 # location in the file, chunk ID, length of chunk, real start location, length
   1: 58598 67108864 0 67108864
   ...
   45: 58661 67108864 0 67108864
   46: 58662 41895936 0 41895936

juicefs lsof

List recently (within 10 minutes) opened files in JuiceFS.

Synopsis

juicefs lsof PATH

juicefs import

juicefs import only collects metadata of the existing files, and save to the metadata engine of the JuiceFS cloud service, this gives JuiceFS access to existing object storage files, but the file data will remain in the object storage as is. For imported files, you can change the file properties as you like, e.g. file name, permissions, etc. But these changes will not be reflected in the object storage. Similarly, deleting imported files in JuiceFS will only delete the associating metadata, not the actual files in the object storage.

Also, imported files will not be able to utilize the powerful JuiceFS cache design.

As explained above, while juicefs import can bring basic access for existing files in object storage, it cannot provide a high-performance experience, so if this is a concern, we strongly recommend you to fully copy existing data into JuiceFS. Juicesync is the recommended tool if you need to move data in and out of JuiceFS, but thanks to POSIX compatibility of JuiceFS, you can use any other tool you like.

Synopsis

juicefs import URI DST [-v] [--name=<name>] [--mode=<mode>]

Options

Items	Description
URI	The URI of the file you are importing. It should be in the format of <bucket_name>[.<domain>][/<prefix>].
DST	The destination of the imported file.
--name=NAME	The name of the file system. This is required in systems other than Linux.
--mode=MODE	Mode (Unix permissions) of imported files.
-v	Run verbosely.
--conf-dir=CONFDIR	a directory for configuration (default: /root/.juicefs)
--no-update	client will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior (usually not needed)

Notes

1. The imported file will be read-only. However, you can still modify other attributes (e.g. filename, permissions) of the files and directories.
2. If you delete the imported file in JuiceFS, the data stored in your object storage will NOT be deleted.

juicefs rmr

Remove all the files and subdirectories, similar to rm -rf, except this command deals with metadata directly (bypassing POSIX API), thus is much faster.

It will try to remove them using current UID/GID, ignore those that can't be removed, return the number of removed files/directories, the number of left ones.

If trash is enabled, deleted files are moved into trash. Files inside trash is still billable, read more at Trash.

Synopsis

juicefs rmr DIR

juicefs snapshot

Manage JuiceFS snapshots.

Taking a snapshot of your data at a certain time, and JuiceFS will create a copy of the corresponding metadata, without copying the actual file data in the object storage, so the snapshot process is much faster compared to a straightforward copy. Snapshots work in copy-on-write fashion, meaning it will only copy the original data when changes are introduced on relevant files.

Snapshotting creates a copy of relevant metadata and will result in an increase in bill, pay special attention when taking snapshots on directories with large amount of files.

Synopsis

juicefs snapshot SRC DST [-f|--force] [-c|--copy]  # create a snapshot
juicefs snapshot -d DST [-f|--force]  # delete a snapshot

Options

Items	Description
SRC	The path to the file you are creating the snapshot from.
DST	The locate where you want to store your snapshot.
-d --delete	Remove the snapshot.
-f --force	Overwrite existing snapshot, or remove the snapshot arbitrarily.
-c --copy	Use current user's UID, GID and umask to create the snapshot. Otherwise it will use permission information of the file you are creating snapshot.

juicefs grep

Parallelized file pattern searcher.

Synopsis

juicefs grep [PATTERN] PATH ... [options]

Options

Items	Description
[PATTERN]	Support simple pattern and basic regular expression.
PATH	Search path and files.
-j JOBS --jobs=JOBS	Number of parallel jobs (default is number of CPU cores).
-e PATTERNS --regexp PATTERNS	This option is most useful when multiple -e options are used to specify multiple patterns, or when a pattern begins with a dash (-).
-E extended-regexp	Interpret pattern as an extended regular expression.
-H	Always print filename headers with output lines.
-n --line-number	Each output line is preceded by its relative line number in the file, starting at line 1.
-i --ignore-case	Perform case insensitive matching. By default, it is case sensitive.
-v --invert-match	Selected lines are those not matching any of the specified patterns.

juicefs profile

Performs basic profiling based on access log, and writes comprehensive statistics to command line output. Use this command to quickly identify the overall file system access pattern of your application, and assess performance.

Synopsis

juicefs profile [options]

Options

Items	Description
-x PATH --path=PATH	The directory path of access log, default to /jfs.
-f FILE --file=FILE	The filename of the access log, default to .ophistory. Refer to Access Log for different types of access log.
-g GROUP_BY --group-by=GROUP_BY	Group the output by a specific attribute, default to cmd, choose from uid, pid, cmd.
-s SORT_BY --sort-by=SORT_BY	Sort the output by a specific column, default to total_time, choose from group, number, avg_time, total_time.
-u FILTER_BY_UID --filter-by-uid=FILTER_BY_UID	Filter the output by one or multiple keywords on the UID column, please separate multi keywords by comma (,).
-p FILTER_BY_PID --filter-by-pid=FILTER_BY_PID	Filter the output by one or multiple keywords on the PID column, please separate multi keywords by comma (,).
-w WINDOW_SIZE --window-size=WINDOW_SIZE	Analysis time window, accept float value, default to 60 seconds.
-i FLUSH_INTERVAL --flush-interval=FLUSH_INTERVAL	Flush output interval, accept float value, default to 2 seconds.

juicefs benchmark

Run benchmark, including read/write/stat big/small files.

Synopsis

juicefs benchmark [options] path-to-test

Options

Items	Description
--dest=DEST	(default: /jfs/benchmark) path to run benchmark
--block-size=BLOCK_SIZE	(default: 1MiB) block size in MiB
--bigfile-file-size=BIGFILE_FILE_SIZE	(default: 1024MiB) size of big file in MiB
--smallfile-file-size=SMALLFILE_FILE_SIZE	(default: 0.1MiB) size of small file in MiB
--smallfile-count=SMALLFILE_COUNT	(default: 100) number of small files

juicefs doctor

Collect abundant debug information, including access log, client log, CPU stats, Goroutine stacktraces. When run into unexpected situations, JuiceFS team may asks you to collect information with this command, and send back the result to continue support.

We encourage you to also take a look at Troubleshooting Methods and Troubleshooting Cases, and try to solve some of the more frequently encountered problems by yourself.

Synopsis

juicefs doctor MOUNTPOINT

juicefs warmup

Download data to local cache in advance, to achieve better performance on application's first read. Executing this command in any cache group member will have the same effect.

Synopsis

juicefs warmup [PATH] [options]

Options

Items	Description
-f LISTFILE, --listfile=LISTFILE	file containing a list of paths (one path per line)
-c CONCURRENT, --concurrent=CONCURRENT	Download concurrency, default to 50. If the download bandwidth of the object storage is small, you need to reduce the concurrency to make the warm-up process more stable.
-b	run in background

juicefs version

Show the JuiceFS version information. The update details of each version can be viewed on the "Release Notes".

Synopsis

juicefs version [options]

Options

Items	Description
-u --upgrade	Upgrade the JuiceFS client to latest version.
-r --restart	Execute seamless remount, if client is upgraded.