Getting Started

System Requirement

  • The data in JuiceFS is stored in a bucket of object storage you provided, a pair of access keys should be provided when it’s mounted for the first time (each machine), which should have permission to read/write/delete objects for given bucket. The key pairs will be stored in your /root/.juicefs, never be uploaded to the JuiceFS. ( Tips: If you don’t know where is the access keys, please refer to the document How to Get Your Access Key and Secret Key from Public Cloud or Storage Provider. )
  • wget or curl to download the client.
  • Python 2.5+ or 3.x with SSL support is required.
  • JuiceFS requires FUSE to be mounted in Linux and macOS, Windows is not supported now. Most of Linux distributions already have FUSE module included. Otherwise, you should rebuild the kernel. For macOS, FUSE for macOS is recommended to for JuiceFS.

Create a Filesystem

First of all, you should sign up a user account of JuiceFS <>. Second, you could create first file system now. 😍


In the above form, something you MUST attention:

  • Cloud Service Provider & Region: Select the cloud that you used and the region of your object storage. If the cloud or region you want is not listed, please click send a request to fill the form, normally we could support cloud within 72hrs, region within 24hrs.

OK, now you click the blue button Create, and the filesystem would be ready to mount. And you will see the screen as blew.


Next, you could mount the filesystem in the CLI of your system.

Note: When you create a filesystem, the JucieFS will create a bucket as the same name in your object storage, this bucket is used to store all of data of the filesystem.


A Python script called juicefs will be used to mount JuiceFS (Python 2.5+ or 3.x is required).

$ curl -L -o juicefs && chmod +x juicefs
$ ./juicefs
juicefs COMMAND [options]

COMMAND could be:
auth      authorize a filesystem
mount     mount a filesystem
info      show information of file or directory

Mount a filesystem

Mount in CLI

Each filesystem of JuiceFS has a unique name (case sensitive),a randomly generated token is used for authorization. When a filesystem is mounted for the first time on a machine, the token and access keys for given bucket of object storage will be asked (The access keys will only be remembered under /root/.juicefs, will never be sent anywhere).

$ sudo ./juicefs mount NAME-OF-JUICEFS  /jfs

If you are using macOS Catalina, mount by

$ ./juicefs mount NAME-OF-JUICEFS  ~/jfs

If you don’t know how to get your credential from the public cloud. Please refer to this document Getting Your Access Key and Secret Key from Public Cloud or Storage Provider.

JuiceFS will be running in the background once the authorization and mount is completed, and all the log information will be sent to syslog (Facility: LOG_USER).

Remember the token and keys

Instead of typing the token and keys interactively, they could be remembered by using juicefs auth before mounting (automated by scripts):

$ sudo ./juicefs auth --token TOKEN --accesskey ACCESSKEY --secretkey SECRETKEY NAME
$ sudo ./juicefs mount NAME-OF-JUICEFS MOUNTPONT

And you could put them in a JSON file /root/.juicefs/NAME.conf like:

{"token": TOKEN, "accesskeyi": ACCESSKEY, "secretkey": SECRETKEY}

Mount on boot


After copy juicefs as /sbin/mount.juicefs, you could mount JuiceFS using the mountcommand (use juicefs auth to remember the keys first):

$ mount -t juicefs  NAME-OF-JUICEFS /jfs

You could also add it to /etc/fstab, so it could be mounted after reboot:

NAME-OF-JUICEFS   /jfs     juicefs    _netdev   0 0

For more details on these commands, please check the help message of each command.

Note:By default, CentOS 6 will NOT mount network filesystem after boot, run the following command to enable it:

$ sudo chkconfig --add netfs


In the following description, some variables will be used to refer to the values that should be filled in. Please substitute it to the corresponding value:

  • NAME file system name
  • PATH_TO_JUICEFS juicefs path(E.g.: /usr/local/bin/juicefs
  • MOUNTPOINT mount path
  1. Refer to Unmount to ensure that the target mount path is unmounted

  2. Refer to Remember the token and keys to save authorization information in a local file

  3. Create a file com.juicefs.NAME.plist under ~/Library/LaunchAgents:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">
    <plist version="1.0">
  4. Load the file created in the previous step and test whether the loading is successful:

    launchctl load ~/Library/LaunchAgents/com.juicefs.NAME.plist
    launchctl start ~/Library/LaunchAgents/com.juicefs.NAME
  5. If the mount is failed, you can add the following configuration to the plist file above:


    Use the following commands to reload the latest configuration and inspect the output:

    launchctl unload ~/Library/LaunchAgents/com.juicefs.NAME.plist
    launchctl load ~/Library/LaunchAgents/com.juicefs.NAME.plist
    cat /tmp/mycommand.out
    cat /tmp/mycommand.err

Mount JuiceFS from Docker container

JuiceFS could be mounted inside Docker (or other containers), require the permission to access FUSE device from the container, which could be granted while launching the Docker with these options:

docker run --cap-add SYS_ADMIN --device=/dev/fuse --security-opt apparmor:unconfined

Import existing objects

For the files that are already in object storage, can be easily imported into JuiceFS, to have all the benefits of JuiceFS without moving or copying them.

They could be imported like this:


For example, the following command could import all the files in my-bucket with prefix my-files into a directory my-files in JuiceFS:

$ sudo ./juicefs import my-bucket/my-files /jfs/my-files

It will only load the metadata into JuiceFS, the files are still in object storage, you can access them as usual. After importing, you can change the attributes of files (including renaming) just like they are created in JuiceFS, these change will NOT sync back into object storage, deleting an imported file in JuiceFS will NOT delete the underlying file in object storage.

Note: The same key pair is used to access imported files, please make sure that the key has read permission on the imported bucket.

Create a Snapshot

JuiceFS supports atomic snapshot, you could make a copy of file or directory instantly. The snapshot reuses the underlying data blocks, only the blocks that are modified later will be copied.

A snapshot could be created like this:

$ ./juicefs snapshot SRC DST

You could also remove the whole snapshot quickly by:

$ ./juicefs snapshot -d DST

Note: ./juicefs snapshot -d can only remove the snapshot. Otherwise, it will say ‘Operation not permitted’.


JuiceFS can be unmounted using umount command.

$ sudo umount /jfs

If the mount point is busy (some files or directories are open), it can be unmounted lazily/forcely by the following commands:

$ sudo umount /jfs -l                # for Linux
$ sudo diskutil unmount force /jfs   # for Mac

The juicefs and jfsmount process will exit after the files are closed, or you can safely kill them.