Skip to main content

Command Reference

Running juicefs by itself and it will print all available commands. In addition, you can add -h/--help flag after each command to get more information, e.g., juicefs mount -h.

juicefs COMMAND [options]

COMMAND could be:
auth authorize a filesystem
mount mount a filesystem
umount umount a filesystem
info show internal information of a path or inode
status show status of a volume
stats show real time performance statistics of JuiceFS
summary Show data and files distribution of a directory
sync sync between two storages
lsof list recent opened files
load load metadata from a previously dumped JSON file
webdav Start a WebDAV server
gateway start an S3-compatible gateway
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)
bench run benchmark (via go binary)
benchmark run benchmark
objbench run benchmarks on an object storage
doctor collect diagnose information
fsck check consistency of a volume
gc garbage collector of objects in data storage
warmup build cache for target directories/files
version show the version

Admin

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]

juicefs auth myjfs --token xxx --access-key xxx --secret-key xxx

Options

ItemsDescription
NAMEName of your file system.
--token=TOKENToken of your file system, obtain in JuiceFS Web Console.
--bucket=BUCKETWhen a file system is first created, object storage bucket is already specified in the web console. When in need, client can override this setting by specifying this option, in order to for example, connect to object storage in special network environments.

Same as the file system bucket setting in the web console, you can either specify the bare bucket name string, or the full endpoint starting with https:// or http://. These two method have different implications:

  • If a bare bucket name is specified, client will automatically conduct a network test to choose between internal/external endpoints (if service provider supports), for example, when using OSS beijing region, passing --bucket=test causes client to automatically choose between https://oss-cn-beijing-internal.aliyuncs.com and https://oss-cn-beijing.aliyuncs.com, according to the network test result.
  • Explicitly specifying --bucket=https://oss-cn-beijing-internal.aliyuncs.com, then client will respect this setting, without trying to deduce the full endpoint by itself.
--access-key=ACCESSKEYObject storage access key, see How to get AK/SK. An interactive prompt will occur to collect this info if missing in the command line options. Leave empty if you have configured host to access object storage without credentials.
--secret-key=SECRETKEYObject storage secret key, see How to get AK/SK. An interactive prompt will occur to collect this info if missing in the command line options. Leave empty if host have been configured to access object storage without credentials.
--session-token=SESSIONTOKENOptionally provide object storage session token.
--bucket2=BUCKET2Optionally provide the name or endpoint for the secondary bucket For Data replication, same format and caveats as --bucket.
--access-key2=ACCESSKEY2When 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=SECRETKEY2When 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_TOKEN2the session token to access the bucket (optional)
--passphrase=PASSPHRASEPassphrase for encrypted key, see Data Encryption for more.
--subdir=SUBDIRSpecify 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=CONFDIRDirectory to store configuration files, default to ~/.juicefs)
--no-updateClient 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.

juicefs gc

Deal with leaked objects, and garbage fragments produced by file overwrites.

Synopsis

juicefs gc [command options] VOLUME-NAME

# Check and print results, but don't actually delete anything
juicefs gc $VOL_NAME

# Delete leaked objects
juicefs gc $VOL_NAME --delete

Options

ItemsDescription
--deletedelete leaked objects (default: false)
--threads=10, -p 10Number of concurrent threads, default to 10.

juicefs fsck

Check consistency of file system.

Synopsis

juicefs fsck [command options] VOLUME-NAME

juicefs fsck $VOL_NAME

Options

ItemsDescription
--threads=10, -p 10Number of concurrent threads, default to 10.
--repairFix the prefix of objects.

juicefs dump

Dump metadata into a JSON file. Different from JuiceFS CE, JuiceFS EE require no manual metadata dump in order to make a backup, it's already handled by our engineers in the server end. Thus, this command is used mainly for debugging, or migration between CE and EE.

Synopsis

juicefs dump [command options] PATH JSON-PATH

# Export metadata to meta-dump.json
juicefs dump /jfs meta-dump.json

# Export metadata for only one subdirectory of the file system
juicefs dump /jfs/subdir meta-dump.json

Options

ItemsDescription
PATHMount point path.
JSON-PATHExport file path. If the filename ends with .gz, it will be automatically compressed.
--gzipCompress with gzip.

juicefs load

Load metadata into an empty file system, often used for migrations between JuiceFS CE and EE.

Synopsis

juicefs load [command options] PATH [FILE]

# Import the metadata backup file into the file system
juicefs load /mnt/jfs meta-dump.json.gz

juicefs version

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

Synopsis

juicefs version [options]

# Upgrade client version and seamless restart
juicefs version -u -r

Options

ItemsDescription
-u --upgradeUpgrade the JuiceFS client to latest version.
-r --restartExecute seamless remount, if client is upgraded.

juicefs quota

Manage directory quota. Different from Community Edition, JuiceFS Enterprise Edition manages quota directly from the web console, and users should not directly run this command from the terminal. The purpose of this command is to stay consistent with CE interface, so that CSI Driver may approach quota management using the same code.

juicefs heal

Repair data when using data replication. Execute a bidirectional synchronization on object storage for both file system.

Synopsis

juicefs heal VOL-NAME [options]

Option

ItemsDescription
--start=valueSpecify object storage key range.
-v --verboseDisplay more log.
--upload-limit=0Maximum bandwidth for upload in Mbps, default to 0 (unlimited).
--conf-dir=/root/.juicefsa directory for configuration (default: /root/.juicefs)

Inspector

juicefs status

Show status of JuiceFS.

Synopsis

juicefs status [command options] VOLUME-NAME

juicefs status $VOL_NAME

Options

ItemsDescription
--session=0 -s 0Show detailed information of one session, specified using a session ID (get from the SID field from the status output).

juicefs stats

The stats command reads the metrics of the JuiceFS client and prints the changes of each metric per second.

For more introduction and usage of this command, see "Real-time Performance Monitoring".

Synopsis

juicefs stats [options] MOUNTPOINT

Options

ItemsDescription
--schema=ufmcoSchema string that controls the output, default to “ufmco”, its meaning:
u: usage
f: FUSE
m: meta
c: blockcache
o: object
g: go
--interval=1Update interval in seconds, default to 1.
--verbosity=0Verbosity level, increase to see more information.

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.

For more introduction and usage of this command, see "Real-time Performance Monitoring".

Synopsis

juicefs profile [options]

Options

ItemsDescription
-x PATH --path=PATHThe directory path of access log, default to /jfs.
-f FILE --file=FILEThe filename of the access log, default to .ophistory. Refer to Access Log for different types of access log.
-g GROUP_BY --group-by=GROUP_BYGroup the output by a specific attribute, default to cmd, choose from uid, pid, cmd.
-s SORT_BY --sort-by=SORT_BYSort 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_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_SIZEAnalysis time window, accept float value, default to 60 seconds.
-i FLUSH_INTERVAL --flush-interval=FLUSH_INTERVALFlush output interval, accept float value, default to 2 seconds.

juicefs info

Show internal information of a path or inode.

Synopsis

juicefs info [options] [PATH|INODE]

# Lookup single file
juicefs info /jfs/foo.txt

# Lookup directory
juicefs info /jfs/bar/

# Reverse lookup on inode
juicefs info 754051

Options

ItemsDescription
`PATHINODE`
-n, --plainShow numbers in plain format.

juicefs summary

Show tree summary of target directory.

Synopsis

juicefs summary [command options] PATH

# Show with path
juicefs summary /jfs/foo

# Show max depth of 5
juicefs summary --depth 5 /jfs/foo

# Show top 20 entries
juicefs summary --entries 20 /jfs/foo

Options

ItemsDescription
--depth=2 -d 2Depth of tree to show, 0 means only show root, defaults to 2.
--entries=10 -e 10Show top N entries, sort by size, defaults to 10.
--csvPrint summary in csv format.

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 lsof

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

Synopsis

juicefs lsof PATH

Service

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

ItemsDescription
NAMEThe name of your file system.
MOUNTPOINTThe mount point for your file system.
--update-fstabadd or update entry in /etc/fstab, when applicable, see Auto-mount on boot.
-f --foregroundRun in the foreground mode, client logs will print directly to console, often used in debugging.
-b --backgroundRun in the background mode, which is the default behavior.
--subdir=SUBDIRSpecify 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=ADDRESSThe bind address to serve files using HTTP, for example, localhost:8080.
--disallow-listDisallow list a directory in WebDAV
--log=LOGPATHLog file location, defaults to /var/log/juicefs.log (when running as root) or ~/.juicefs/log/juicefs.log (when running as normal user).
-v --verbosePrint verbose log.
--no-updateClient 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

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=20Upload 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-downloads=200Max number of concurrent downloads, default to 200, which is usually large enough for clients and does not require further adjustments.
--prefetch=1When 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=0Maximum 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=0Maximum 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=DELETELIMITMaximum QPS for deletion default to 0 (unlimited). Use this if for example, some object storage limit API calls.
--get-timeout=60Max number of seconds to download an object, default to 60, may need to increase this in low bandwidth conditions, see Read / Write error.
--put-timeout=60Max number of seconds to upload an object, default to 60, may need to increase this in low bandwidth conditions, see Read / Write error.
--gcAfter 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.
--dryOnly check for garbage in object storage when running gc, but do not delete them.
--flipWhen data replication is enabled, use secondary bucket as primary bucket. Learn more at Cross-region data replication.

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

Read Cache to understand JuiceFS's cache design.

ItemsDescription
--cache-dir=CACHEDIRCache directory, defaults to /var/jfsCache or $HOME/.juicefs/cache depending on the current user.

Separate multiple directories by :, add quotation mark if using wildcard match (*). e.g. --cache-dir '/data*/jfsCache:/mydata*/jfsCache'.

Moreover, you can specify /dev/shm to use the memory device (defaults to half of node memory), or use the string memory to use client process memory.
--cache-size=102400Local 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). Set to 0 to disable cache altogether.
--cache-eviction="2-random"Cache eviction algorithm, supports the following strategies:
  • 2-random (default): Evict cache using 2-random algorithm, i.e. randomly choose two blocks, and evict the one with a lower atime (last access time). For most real-world scenarios, this algorithm approximates LRU.
  • none: Disable cache eviction altogether, new cache will not write once cache capacity is drained. You'll have to manually free up cache space.
--free-space-ratio=0.2Minimum free space ratio on cache disk, default to 0.2. This option doesn't support being set to 0, to achieve maximum usage, you can set a value close to 0 (such as 0.01). Also if Client write cache is enabled, this option also controls write cache size
--buffer-size=300Total size of memory used for read/write buffering in MiB default to 300, learn more at Read/Write Buffer
--cache-mode="0600"File permission for cached blocks, default to 0600.
--cache-group=CACHEGROUPCache group name for distributed cache. Nodes within the same group share cache, disabled by default.
--subgroups=SUBGROUPSthe number of sub-groups in a cache group (default: 0)
--group-ip=GROUPIPManually set IP address listened by distributed cache, in hosts with multiple network interfaces, use this option to specify the correct NIC. Can also use CIDR prefix to automatically select IP, e.g. use 172.16.0.0 to match with 172.16.0.0/16.
--no-sharingWhen inside a cache group, only fetch cache data from others, but never share its own cache. Use this option on ephemeral mount points (like Kubernetes Pod). Default to false.
--writebackEnable client write cache, data will be written to local disk first, and then uploaded asynchronously in the background, default to false. Client write cache brings data security risks, use with caution.
--cache-partial-onlyOnly cache files and reads smaller than block size, default to false. Enable this when you need to frequently access a same set of small files, or when disk throughput is smaller than object storage throughput.
--verify-cache-checksum=fullChecksum 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:
  • none: Disable checksum verification, if local cache data is tampered, bad data will be read;
  • full (default): Perform verification when reading the full block, use this for sequential read scenarios;
  • shrink: Perform verification on parts that's fully included within the read range, use this for random read scenarios;
  • 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.
--fill-group-cacheNewly written blocks are sent to distributed cache, rather than local disk cache. This option is not affected by --no-sharing, i.e. clients using a dedicated cache cluster will still contribute their writes to the cache group. However, if --writeback is enabled, this option will cease to work.
--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 files 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. For the same mount point, open cache is automatically invalidated upon file modifications.
--attrcacheto=ATTRCACHETOFile attribute cache timeout in seconds, default to 1.
--entrycacheto=ENTRYCACHETOFile entry cache timeout in seconds, default to 1.
--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, default to false, which is recommended for most scenarios because xattr comes with its own overhead.
--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 file system in the document Getting Started.

Experimental Options

ItemsDescription
--min-inodes-diff=MININODESDIFFWhen 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

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

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

Umount a JuiceFS file system. This command handles the platform differences, i.e. umount in Linux and diskutil unmount in macOS. Note that there's a similar hidden command called juicefs unmount, this is specially reserved for Kubernetes FlexVolume and not for normal use.

If you encounter any errors while unmounting JuiceFS, read the docs for troubleshooting steps.

Synopsis

juicefs umount PATH [options]

Options

ItemsDescription
PATHThe mount point for your file system.
-f --forceUmount it forcibly.

juicefs gateway

Start an S3 gateway, read S3 gateway for more.

Synopsis

juicefs gateway [command options] VOLUME-NAME ADDRESS

export MINIO_ROOT_USER=admin
export MINIO_ROOT_PASSWORD=12345678
juicefs gateway testVolume localhost:9000

Options

Apart from options listed below, this command shares options with juicefs mount, be sure to refer to mount as well.

FlagDescription
--open-cache=0Same as --opencache.
--console-url=URLWeb URL address, only needed in on-premise environments.
--access-log=PATHPath for file system access log, default location is the .accesslog file under the root mount point.
--no-bannerOmit MinIO startup messages.
--multi-bucketsUse top level directories as buckets, default to false.
--keep-etagKeep object ETag when uploading.
--umask="022"Umask used for new files, default to 022.

juicefs webdav

Start a WebDAV server to access JuiceFS file system.

Use the environment variable WEBDAV_USERNAME and WEBDAV_PASSWORD to set the username and password for WebDAV server.

Synopsis

juicefs webdav [command options] NAME ADDRESS

# Set username and password
export WEBDAV_USER=root
export WEBDAV_PASSWORD=1234

# Start WebDAV server on port 9007
juicefs webdav myjfs localhost:9007

Options

Apart from options listed below, this command shares options with juicefs mount, be sure to refer to mount as well.

ItemsDescription
--cert-filecertificate file for TLS
--key-filekey file for TLS

Tool

juicefs benchmark

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

Synopsis

juicefs benchmark [options] path-to-test

Options

ItemsDescription
--dest=/jfs/benchmarkTemporary directory for benchmark test files, default to /jfs/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=100(default: 100) number of small files

juicefs objbench

Run basic benchmarks on the target object storage to test if it works as expected.

Synopsis

juicefs objbench [command options] BUCKET

Options

ItemsDescription
--storage=fileObject storage type (e.g. s3, gcs, oss, cos) (default: file)
--access-key=valueAccess Key for object storage (can also be set via the environment variable ACCESS_KEY)
--secret-key valueSecret Key for object storage (can also be set via the environment variable SECRET_KEY)
--session-token=valueSession token for object storage
--block-size=4096size of each I/O block in KiB (default: 4096)
--big-object-size=1024size of each big object in MiB (default: 1024)
--small-object-size=128size of each small object in KiB (default: 128)
--small-objects=100number of small objects (default: 100)
--skip-functional-testsskip functional tests (default: false)
--threads=4, -p 4number of concurrent threads (default: 4)

juicefs warmup

Download data to local cache in advance, to achieve better performance on application's first read. You can specify a mount point path to recursively warm-up all files under this path. You can also specify a file through the --file option to only warm-up the files contained in it.

If the files needing warming up resides in many different directories, you should specify their names in a text file, and pass to the warmup command using the --file option, allowing juicefs warmup to download concurrently, which is significantly faster than calling juicefs warmup multiple times, each with a single file.

The warmup command will not repeatedly download files that already exist locally (it will be skipped directly), so the displayed download speed may be higher than the actual download traffic. If the distributed cache is enabled, executing this command on any node in the cache group can achieve the same effect.

Synopsis

juicefs warmup [PATH] [options]

# Warm up all files in datadir
juicefs warmup /mnt/jfs/datadir

# Warm up selected files
echo '/jfs/f1
/jfs/f2
/jfs/f3' > /tmp/filelist.txt
juicefs warmup -f /tmp/filelist.txt

Options

ItemsDescription
-f value, --file=value, --listfile=valuefile containing a list of paths (one path per line)
-c 50, --concurrent=50Download concurrency, default to 50. Increase concurrency to speed up, but if the download bandwidth of the object storage is low, reduce concurrency to avoid download timeout errors.
--io-retries=1Max number of allowed retries, default to 1. Increase this value in poor network conditions to better handle failures.
--max-failure=0Controls the command exit code according to the number of download failures, the number of allowed failures is default to 0, meaning that upon any data block warmup failure, command exits with error (exit code 1). When faced with warmup errors, check client logs for troubleshooting.
-b --backgroundRun in the background.

juicefs snapshot

Also called juicefs clone. This command takes a snapshot of your data by creating a mere metadata copy, without creating any new data in the object storage, thus snapshotting is very fast regardless of target file / directory size. Under JuiceFS, this command is a better alternative to cp, moreover, for Linux clients using kernels with copy_file_range support, then the cp command achieves the same result as juicefs snapshot.

clone

Snapshot result is a metadata copy, all the files are still referencing the same object storage blocks, that's why a snapshot behaves the same in every way as its originals. When either of them go through actual file data modification, the affected data blocks will be copied on write, and become new blocks after write, while the unchanged part of the files remains the same, still referencing the original blocks.

Although object storage data is not actually copied, snapshots takes up storage space, and will result in an increase in bill, pay special attention when taking snapshots on large size directories.

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. Only use this command on snapshots, deleting normal files using this command will result in permission errors. Deleted snapshots will bypass Trash completely. If you want to preserve the deleted snapshots in Trash like normal files, use juicefs rmr or simply rm -r.
-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 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 sync

Sync data between two storage systems, read Data Migration for more.

Synopsis

juicefs sync [command options] SRC DST

# Sync object from OSS to S3
juicefs sync oss://mybucket.oss-cn-shanghai.aliyuncs.com s3://mybucket.s3.us-east-2.amazonaws.com

# Sync objects from S3 to JuiceFS
juicefs sync s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

# SRC: a1/b1,a2/b2,aaa/b1 DST: empty sync result: aaa/b1
juicefs sync --exclude='a?/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

# SRC: a1/b1,a2/b2,aaa/b1 DST: empty sync result: a1/b1,aaa/b1
juicefs sync --include='a1/b1' --exclude='a[1-9]/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

# SRC: a1/b1,a2/b2,aaa/b1,b1,b2 DST: empty sync result: a1/b1,b2
juicefs sync --include='a1/b1' --exclude='a*' --include='b2' --exclude='b?' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

Both SRC and DST takes up the format [NAME://][ACCESS_KEY:SECRET_KEY[:SESSIONTOKEN]@]BUCKET[.ENDPOINT][/PREFIX], in which:

  • NAME: Can be all JuiceFS supported storage, e.g. s3, oss, even jfs. Using jfs:// allows you to directly transfer data from or into JuiceFS, bypassing the FUSE mount point, this saves resource under large scale data transfer.
  • ACCESS_KEY and SECRET_KEY: Object storage credentials, if special characters are included, use single quote to avoid shell interpretations.
  • SESSIONTOKEN: Optionally provide session token for the object storage.
  • BUCKET[.ENDPOINT]: Object storage endpoint, note that currently MinIO only supports path style (minio://[ACCESS_KEY:SECRET_KEY[:TOKEN]@]ENDPOINT/BUCKET[/PREFIX]).
  • [/PREFIX]: Optionally provide the prefix of the files to synchronize.
tip

Apart from options listed below, this command shares options with juicefs mount, be sure to refer to mount as well.

Do notice that many of these shared options works exclusively with jfs scheme, for example, the sync command supports --writeback as well, but if the sync destination is a normal JuiceFS FUSE mount point, it won't automatically convert itself to a --writeback mount point simply because you are running a sync job with --writeback. To sum up, --writeback only works when sync destination is a jfs scheme address, and this is also true for many other options that's shared with mount.

ItemsDescription
--start=KEY, -s KEY, --end=KEY, -e KEYProvide object storage key range for syncing.
--exclude=PATTERNExclude keys matching PATTERN.
--include=PATTERNInclude keys matching PATTERN, need to be used with --exclude.
--limit=-1Limit the number of objects that will be processed, default to -1 which means unlimited.
--update, -uUpdate existing files if the source files' mtime is newer, default to false.
--force-update, -fAlways update existing file, default to false.
--existing, --ignore-non-existingSkip creating new files on destination, default to false.
--ignore-existingSkip updating files that already exist on destination, default to false.
ItemsDescription
--dirsSync empty directories as well.
--permsPreserve permissions, default to false.
--inplaceModify files in place, rather than delete and replace. If destination storage system is a JuiceFS volume with Trash enabled, overwritten files by default will be kept in Trash. Use --inplace to modify files in place and prevent Trash usage. Currently only jfs:// type destination storage is supported.
--links, -lCopy symlinks as symlinks default to false.
--delete-src, --deleteSrcDelete objects that already exist in destination. Different from rsync, files won't be deleted at the first run, instead they will be deleted at the next run, after files are successfully copied to the destination.
--delete-dst, --deleteDstDelete extraneous objects from destination.
--check-allVerify the integrity of all files in source and destination, default to false. Comparison is done on byte streams, which comes at a performance cost.
--check-newVerify the integrity of newly copied files, default to false. Comparison is done on byte streams, which comes at a performance cost.
--dryDon't actually copy any file.
--http-port=6070HTTP port for the pprof server to listen on, default to 6070.
ItemsDescription
--threads=10, -p 10Number of concurrent threads, default to 10.
--list-threads=1Number of list threads, default to 1. Read concurrent list to learn its usage.
--list-depth=1Depth of concurrent list operation, default to 1. Read concurrent list to learn its usage.
--no-httpsDo not use HTTPS, default to false.
--storage-class=valueStorage class for the destination storage, if supported.
--bwlimit=0Limit bandwidth in Mbps default to 0 which means unlimited.
ItemsDescription
--manager=ADDRManager node address used in distributed syncing, this is an internal option that's used in the executed command on the worker nodes.
--worker=ADDR,ADDRWorker node addresses used in distributed syncing, comma separated.

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. juicefs sync 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

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 file system. This is required in systems other than Linux.
--mode=MODEMode (Unix permissions) of imported files.
-vRun verbosely.
--conf-dir=/root/.juicefsa directory for configuration (default: /root/.juicefs)
--no-updateclient will by default obtain latest config from JuiceFS Web Console, set to true to disable this behavior (usually not needed)

juicefs grep

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.