Skip to main content

Command Reference

JuiceFS provides many commands to help you manage your filesystem. 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

Description

Set up the authentication information configuration file of the file system locally and stored in the $HOME/.juicefs directory of the current user. The name of the configuration file is in the format of [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

ItemsDescription
NAMEThe name of your filesystem.
--token=TOKENThe JuiceFS token of your filesystem, you can find this token in the web console.
--bucket=BUCKETname or endpoint of the bucket (optional)
--access-key=ACCESSKEYThe access key of your bucket, you can read our guide on how to get access key and secret from your service provider.
--secret-key=SECRETKEYThe secret key of your bucket, you can read our guide on how to get access key and secret from your service provider.
--session-token=SESSIONTOKENthe session token to access the bucket (optional)
--bucket2=BUCKET2name or endpoint of the secondary bucket (optional)
--access-key2=ACCESSKEY2The access key of your secondary bucket.
--secret-key2=SECRETKEY2The secret key of your secondary bucket.
--session-token2=SESSION_TOKEN2the session token to access the bucket (optional)
--passphrase=PASSPHRASEpassphrase for encrypted key
--subdir=SUBDIRauth a sub-directory
--conf-dir=CONFDIRa directory for configuration (default: /root/.juicefs)
--no-updateuse local config only

Notes

  1. The authentication information is stored in $HOME/.juicefs/<NAME>.conf.
  2. You will be prompted to enter the access key and secret if you didn't provide it through the --token, --accesskey and --secretkey options.
  3. 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.
  4. Enable JuiceFS replication in the setting panel of the Web Console, and mount with the --accesskey2 and --secretkey2 options.

juicefs mount

Description

Mount the filesystem. 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.

Synopsis

juicefs mount NAME MOUNTPOINT [options]

Options

ItemsDescription
NAMEThe name of your filesystem.
MOUNTPOINTThe mountpoint for your filesystem.
--update-fstabadd or update entry in /etc/fstab, when applicable.
-fRun in the foreground mode.
-bRun in the background mode.
--subdir=SUBDIRmount a sub-directory
--ioretries=IORETRIES(default: 30) number of retries for network failure
--http=ADDRESSThe bind address to serve files using HTTP, for example, localhost:8080.
--disallow-listDisallow list a directory in WebDAV
--log=LOGPATH(default: /var/log/juicefs.log or ~/.juicefs/log/juicefs.log) The path of the log file.
-vRun verbosely.
--no-updateuse local config only

Object Storage Options

ItemsDescription
--externalPrefer 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.
--internalPrefer 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=MAXUPLOADSMax number of concurrent uploads (default: 20)
--prefetch=PREFETCHnumber of concurrent prefetching (default: 1)
--upload-limit=UPLOADLIMITMaximum bandwidth for upload (Mbps, default: unlimited)
--download-limit=DOWNLOADLIMITMaximum bandwidth for download (Mbps, default: unlimited)
--delete-limit=DELETELIMITMaximum qps for deletion (0: disallow, default: unlimited)
--get-timeout=GETTIMEOUTMax number of seconds to get an object (default: 60)
--put-timeout=PUTTIMEOUTMax number of seconds to upload an object (default: 60)
--gccleanup unused chunks after mounting immediately
--drydo not delete chunks during GC
--flipflip the two replicated bucket (prefer secondary bucket)

Security Options

ItemsDescription
--rsa-key=RSAKEYPath to RSA private key (PEM). Passphrase will be asked or provided with JFS_RSA_PASSPHRASE environment variable.

Cache Options

ItemsDescription
--cache-dir=CACHEDIR(default: /var/jfsCache or $HOME/.juicefs/cache) The path of the cache. Separate multiple directories by :, add quotation mark if using wildcard match (*). e.g. --cache-dir '/data*/jfsCache:/mydata*/jfsCache'
--cache-size=CACHESIZE(default: 100GiB) The maximum size of the cache. The default unit is MiB. Will be evenly distributed to each directory in multiple directories mode.
--free-space-ratio=FREESPACEmin free space ratio on cache disk (default: 0.2)
--buffer-size=BUFFERSIZEthe total size of memory used for read/write buffering in MiB (default: 300MiB)
--cache-mode=CACHEMODEfile permission for cached blocks (default: 0600)
--cache-group=CACHEGROUPthe name of group to join and provide remote cache (default: no sharing)
--subgroups=SUBGROUPSthe number of sub-groups in a cache group (default: 0)
--group-ip=GROUPIPIP address for group cache
--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-cachebuild remote cache for new written blocks
--metacacheEnable 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
--opencacheopen a file for read using cached metadata
--attrcacheto=ATTRCACHETO(default: 1) Duration for the attributes of file and directory cached in the kernel (seconds) .
--entrycacheto=ENTRYCACHETO(default: 1) Duration for the file entry cached in the kernel (seconds).
--direntrycacheto=DIRENTRYCACHETOdirectory entry cache timeout in seconds (default: 1)
--readdir-cachecache readdir in kernel (require linux kernel 4.20+)

FUSE Options

ItemsDescription
--allow-otherAllow 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-xattrEnable extended attributes (xattr) support.
--enable-aclEnable POSIX ACL support.
--no-posix-lockDisable POSIX lock support.
--no-bsd-lockDisable BSD lock support.
--block-interrupt=BLOCKINTERRUPT(default: 1) number of seconds to block interruption
-o FUSE_OPTSOther 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 filesystem in the document Getting Started.

Experimental Options

ItemsDescription
--min-balance-diff=MINBALANCEDIFFWhen 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=MINDIRINODESWhen the number of directories in the current path exceeds this value, the metadata is automatically balanced.
--max-space=MAXSPACElimit the total space in GiB (default: no limit)
--source=SOURCEUse JuiceFS as cache for a directory
--refresh-interval=REFRESHINTERVALchecking for update (seconds)
--update-sourcepropagate all changes to source
--fsckcheck consistency

Deprecated Options

note

The following are the options that have been deprecated by JuiceFS!

ItemsDescription
--asyncsee --writeback
--sslUse HTTPS to access object store (always enabled)
--dircachesee --metacache
-dsee -v
--cacheDir=CACHEDIRsee --cache-dir
--cacheSize=CACHESIZEsee --cache-size
--allow-rootallow root to access (use --allow-other instead)
--no-syncdo not sync the replicated object store
--batch=BATCHnumber of seconds to wait to combine multiple small files as single object
--keep-fdkeep FUSE session alive

juicefs umount

Description

Umount a JuiceFS file system.

Synopsis

juicefs umount PATH [options]

Options

ItemsDescription
PATHThe mountpoint for your filesystem.
-f --forceUmount it forcibly.

juicefs info

Description

Show information about the file or directory stored in JuiceFS.

Synopsis

juicefs info PATH [options]

Options

ItemsDescription
PATHThe path to the file you are querying.
-n --plainShow 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

Description

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

Synopsis

juicefs lsof PATH

juicefs import

Description

Import existing files from object storage, see Import existing files.

Synopsis

juicefs import URI DST [options]

Options

ItemsDescription
URIThe URI of the file you are importing. It should be in the format of <bucket_name>[.<domain>][/<prefix>].
DSTThe destination of the imported file.
--name=NAMEThe name of the filesystem. This is required in systems other than Linux.
--mode=MODEMode (Unix permissions) of imported files.
-vRun verbosely.
--conf-dir=CONFDIRa directory for configuration (default: /root/.juicefs)
--no-updateuse local config only

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

Description

Remove all the files and subdirectories, similar to rm -rf, but 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, the removed files are removed into trash.

Synopsis

juicefs rmr DIR

juicefs snapshot

Description

Manage JuiceFS snapshots.

Snapshots are snapshots of your data at a certain time. It is a common technology used in data backup. JuiceFS will not create a copy of your data when you create a snapshot. It will only create a copy when there are some changes made to the original data (i.e. copy-on-write).

Synopsis

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

Options

ItemsDescription
SRCThe path to the file you are creating the snapshot from.
DSTThe locate where you want to store your snapshot.
-d --deleteRemove the snapshot.
-f --forceOverwrite existing snapshot, or remove the snapshot arbitrarily.
-c --copyUse 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

Description

Parallelized file pattern searcher.

Synopsis

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

Options

ItemsDescription
[PATTERN]Support simple pattern and basic regular expression.
PATHSearch path and files.
-j JOBS --jobs=JOBSNumber of parallel jobs (default is number of CPU cores).
-e PATTERNS --regexp PATTERNSThis option is most useful when multiple -e options are used to specify multiple patterns, or when a pattern begins with a dash (-).
-E extended-regexpInterpret pattern as an extended regular expression.
-HAlways print filename headers with output lines.
-n --line-numberEach output line is preceded by its relative line number in the file, starting at line 1.
-i --ignore-casePerform case insensitive matching. By default, it is case sensitive.
-v --invert-matchSelected lines are those not matching any of the specified patterns.

juicefs profile

Description

Collect and analyze the file system's oplog (operation log).

Synopsis

juicefs profile [options]

Options

ItemsDescription
-x PATH --path=PATHThe path of log, default path is /jfs.
-f FILE --file=FILEThe filename of log, default filename is .ophistory. For the differences between log files please refer to "Access Log" document.
-g GROUP_BY --group-by=GROUP_BYGroup the output by a specific attribute (default by cmd), choose from uid, pid, cmd.
-s SORT_BY --sort-by=SORT_BYSort the output by a specific column (default by total_time), choose from group, number, avg_time, total_time.
-u FILTER_BY_UID --filter-by-uid=FILTER_BY_UIDFilter 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_PIDFilter the output by one or multiple keywords on the PID column, please separate multi keywords by comma (,).
-w WINDOW_SIZE --window-size=WINDOW_SIZEThe window size of collect oplog, accept float value, 60 seconds by default.
-i FLUSH_INTERVAL --flush-interval=FLUSH_INTERVALThe interval of flush output, accept float value, 2 seconds by default.

juicefs benchmark

Description

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

Synopsis

juicefs benchmark [options] path-to-test

Options

ItemsDescription
--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

Description

Collect information for debug

Synopsis

juicefs doctor MOUNTPOINT

juicefs warmup

Description

Warm-up cache for the files

Synopsis

juicefs warmup [PATH] [options]

Options

ItemsDescription
-f LISTFILE, --listfile=LISTFILEfile containing a list of paths (one path per line)
-c CONCURRENT, --concurrent=CONCURRENT(default: 50) number of concurrent workers
-brun in background

juicefs version

Description

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

Synopsis

juicefs version [options]

Options

ItemsDescription
-u --upgradeUpgrade the JuiceFS client to latest version.
-r --restartExecute seamless remount when upgrade.