sidebar_label	sidebar_position	slug
Command Reference	1	/command_reference

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Command Reference

There are 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 available commands. In addition, you can add -h/--help flag after each command to get more information of it, e.g., juicefs format -h.

NAME:
   juicefs - A POSIX file system built on Redis and object storage.

USAGE:
   juicefs [global options] command [command options] [arguments...]

VERSION:
   1.0.0+2022-08-01.0e7afe2d

COMMANDS:
   ADMIN:
     format   Format a volume
     config   Change configuration of a volume
     destroy  Destroy an existing volume
     gc       Garbage collector of objects in data storage
     fsck     Check consistency of a volume
     dump     Dump metadata into a JSON file
     load     Load metadata from a previously dumped JSON file
     version  Show version
   INSPECTOR:
     status   Show status of a volume
     stats    Show real time performance statistics of JuiceFS
     profile  Show profiling of operations completed in JuiceFS
     info     Show internal information of a path or inode
   SERVICE:
     mount    Mount a volume
     umount   Unmount a volume
     gateway  Start an S3-compatible gateway
     webdav   Start a WebDAV server
   TOOL:
     bench     Run benchmarks on a path
     objbench  Run benchmarks on an object storage
     warmup    Build cache for target directories/files
     rmr       Remove directories recursively
     sync      Sync between two storages

GLOBAL OPTIONS:
   --verbose, --debug, -v  enable debug log (default: false)
   --quiet, -q             show warning and errors only (default: false)
   --trace                 enable trace log (default: false)
   --no-agent              disable pprof (:6060) and gops (:6070) agent (default: false)
   --pyroscope value       pyroscope address
   --no-color              disable colors (default: false)
   --help, -h              show help (default: false)
   --version, -V           print version only (default: false)

COPYRIGHT:
   Apache License 2.0

:::note If juicefs is not placed in your $PATH, you should run the script with the path to the script. For example, if juicefs is in current directory, you should use ./juicefs. It is recommended to place juicefs in your $PATH for convenience. You can refer to "Installation" for more information. :::

:::note If the command option is of boolean type, such as --debug, there is no need to set any value, just add --debug to the command to enable the function; this function is disabled if --debug is not added. :::

Auto Completion

:::note This feature requires JuiceFS >= 0.15.2. It is implemented based on github.com/urfave/cli/v2. You can find more information here. :::

To enable commands completion, simply source the script provided within hack/autocomplete directory. For example:

source hack/autocomplete/bash_autocomplete

source hack/autocomplete/zsh_autocomplete

Please note the auto-completion is only enabled for the current session. If you want to apply it for all new sessions, add the source command to .bashrc or .zshrc:

echo "source path/to/bash_autocomplete" >> ~/.bashrc

echo "source path/to/zsh_autocomplete" >> ~/.zshrc

Alternatively, if you are using bash on a Linux system, you may just copy the script to /etc/bash_completion.d and rename it to juicefs:

sudo cp hack/autocomplete/bash_autocomplete /etc/bash_completion.d/juicefs

source /etc/bash_completion.d/juicefs

Commands

juicefs format

Description

Format a volume. It's the first step for initializing a new file system volume.

Synopsis

juicefs format [command options] META-URL NAME

META-URL: Database URL for metadata storage, see "JuiceFS supported metadata engines" for details.
NAME: the name of the file system

Options

--block-size value
size of block in KiB (default: 4096)

--capacity value
the limit for space in GiB (0 means unlimited) (default: 0)

--inodes value
the limit for number of inodes (0 means unlimited) (default: 0)

--compress value
compression algorithm (lz4, zstd, none) (default: "none")

--shards value
store the blocks into N buckets by hash of key (default: 0)

--storage value
Object storage type (e.g. s3, gcs, oss, cos) (default: "file", please refer to documentation for all supported object storage types)

--bucket value
A bucket URL to store data (default: "$HOME/.juicefs/local" or "/var/jfs")

--access-key value
Access Key for object storage (can also be set via the environment variable ACCESS_KEY)

--secret-key value
Secret Key for object storage (can also be set via the environment variable SECRET_KEY)

--session-token value
session token for object storage

--encrypt-rsa-key value
A path to RSA private key (PEM)

--trash-days value
number of days after which removed files will be permanently deleted (default: 1)

--force
overwrite existing format (default: false)

--no-update
don't update existing volume (default: false)

Examples

# Create a simple test volume (data will be stored in a local directory)
$ juicefs format sqlite3://myjfs.db myjfs

# Create a volume with Redis and S3
$ juicefs format redis://localhost myjfs --storage s3 --bucket https://mybucket.s3.us-east-2.amazonaws.com

# Create a volume with password protected MySQL
$ juicefs format mysql://jfs:mypassword@(127.0.0.1:3306)/juicefs myjfs
# A safer alternative
$ META_PASSWORD=mypassword juicefs format mysql://jfs:@(127.0.0.1:3306)/juicefs myjfs

# Create a volume with "quota" enabled
$ juicefs format sqlite3://myjfs.db myjfs --inode 1000000 --capacity 102400

# Create a volume with "trash" disabled
$ juicefs format sqlite3://myjfs.db myjfs --trash-days 0

juicefs mount

Description

Mount a volume. The volume shoud be formatted first.

Synopsis

juicefs mount [command options] META-URL MOUNTPOINT

META-URL: Database URL for metadata storage, see "JuiceFS supported metadata engines" for details.
MOUNTPOINT: file system mount point, e.g. /mnt/jfs, Z:.

Options

--metrics value
address to export metrics (default: "127.0.0.1:9567")

--consul value
consul address to register (default: "127.0.0.1:8500")

--no-usage-report
do not send usage report (default: false)

-d, --background
run in background (default: false)

--no-syslog
disable syslog (default: false)

--log value
path of log file when running in background (default: $HOME/.juicefs/juicefs.log or /var/log/juicefs.log)

-o value
other FUSE options (see this document for more information)

--attr-cache value
attributes cache timeout in seconds (default: 1)

--entry-cache value
file entry cache timeout in seconds (default: 1)

--dir-entry-cache value
dir entry cache timeout in seconds (default: 1)

--enable-xattr
enable extended attributes (xattr) (default: false)

--bucket value
customized endpoint to access object storage

--get-timeout value
the max number of seconds to download an object (default: 60)

--put-timeout value
the max number of seconds to upload an object (default: 60)

--io-retries value
number of retries after network failure (default: 10)

--max-uploads value
number of connections to upload (default: 20)

--max-deletes value
number of threads to delete objects (default: 2)

--buffer-size value
total read/write buffering in MiB (default: 300)

--upload-limit value
bandwidth limit for upload in Mbps (default: 0)

--download-limit value
bandwidth limit for download in Mbps (default: 0)

--prefetch value
prefetch N blocks in parallel (default: 1)

--writeback
upload objects in background (default: false)

--cache-dir value
directory paths of local cache, use : (Linux, macOS) or ; (Windows) to separate multiple paths (default: "$HOME/.juicefs/cache" or "/var/jfsCache")

--cache-size value
size of cached objects in MiB (default: 102400)

--free-space-ratio value
min free space (ratio) (default: 0.1)

--cache-partial-only
cache random/small read only (default: false)

--read-only
allow lookup/read operations only (default: false)

--open-cache value
open file cache timeout in seconds (0 means disable this feature) (default: 0)

--subdir value
mount a sub-directory as root (default: "")

--backup-meta value
interval (in seconds) to automatically backup metadata in the object storage (0 means disable backup) (default: "3600")

--heartbeat value
interval (in seconds) to send heartbeat; it's recommended that all clients use the same heartbeat value (default: "12")

--upload-delay value
delayed duration for uploading objects ("s", "m", "h") (default: 0s)

--no-bgjob
disable background jobs (clean-up, backup, etc.) (default: false)

Examples

# Mount in foreground
$ juicefs mount redis://localhost /mnt/jfs

# Mount in background with password protected Redis
$ juicefs mount redis://:mypassword@localhost /mnt/jfs -d
# A safer alternative
$ META_PASSWORD=mypassword juicefs mount redis://localhost /mnt/jfs -d

# Mount with a sub-directory as root
$ juicefs mount redis://localhost /mnt/jfs --subdir /dir/in/jfs

# Enable "writeback" mode, which improves performance at the risk of losing objects
$ juicefs mount redis://localhost /mnt/jfs -d --writeback

# Enable "read-only" mode
$ juicefs mount redis://localhost /mnt/jfs -d --read-only

# Disable metadata backup
$ juicefs mount redis://localhost /mnt/jfs --backup-meta 0

juicefs umount

Description

Unmount a volume.

Synopsis

juicefs umount [command options] MOUNTPOINT

Options

-f, --force
force unmount a busy mount point (default: false)

Examples

$ juicefs umount /mnt/jfs

juicefs gateway

Description

Start an S3-compatible gateway.

Synopsis

juicefs gateway [command options] META-URL ADDRESS

META-URL: Database URL for metadata storage, see "JuiceFS supported metadata engines" for details.
ADDRESS: S3 gateway address and listening port, for example: localhost:9000

Options

--bucket value
customized endpoint to access an object storage