juicedata/juicefs

Overview

JuiceFS is an Apache-2.0 licensed, POSIX-compatible distributed file system for cloud-native environments. It separates storage into two parts: file data is written to object storage such as S3, GCS, MinIO or local disk, while metadata (file names, sizes, permissions, directory structure) lives in a separate metadata engine such as Redis, MySQL, TiKV or SQLite. A client process coordinates the two and presents a normal filesystem interface, so applications can use large cloud storage without changing their code.

It targets data-intensive workloads: big data and Hadoop jobs (a Hadoop Java SDK is provided), machine learning and AI training pipelines, Kubernetes persistent volumes through a CSI driver, and shared storage across many clients. It also offers an S3-compatible gateway. Files are split into chunks, slices and fixed-size blocks (4 MiB by default) before being written to the object store, so the bucket contains JuiceFS's internal layout rather than the original files.

Getting started

Before starting you need three things: a supported metadata engine, a supported object storage backend, and the JuiceFS client installed on the machine where you will mount the file system. See the metadata engine and object storage setup docs, and the client installation page for your platform Windows is also documented.

The README itself does not include the full juicefs format and juicefs mount command sequence; follow the Quick Start Guide rather than copying an incomplete command list. The command reference lists all CLI options.

Core usage paths

• POSIX mount: the main path, mounting JuiceFS as a local directory for existing applications.
• Containers: usable as a persistent volume for Docker and Podman (details).
• Kubernetes: a CSI driver for persistent volumes (details).
• Hadoop: a Java SDK compatible with Hadoop 2.x and 3.x (details).
• S3 API: an S3-compatible gateway for tools that speak S3 (details).

Compatibility and limits

• JuiceFS reports passing all 8813 pjdfstest conformance cases, plus close-to-open consistency, atomic metadata operations, mmap, fallocate with punch hole, xattr, and both flock and fcntl locks.
• Data encryption is supported in transit and at rest. LZ4 and Zstandard compression are available.
• The metadata engine choice matters: performance and deployment topology depend heavily on it, and losing the metadata store means losing access to the data, since the object store holds only opaque chunks. Community discussion raises this tradeoff, and notes that large installations tend to use distributed KV stores such as TiKV or FoundationDB.
• Redis Cluster is supported, but JuiceFS can use only one hash slot per file system, which constrains scale.
• The project collects anonymous usage data by default; disable it with juicefs mount --no-usage-report.
• The storage format is declared stable and forward-supported by future releases.

HotRepo's take

JuiceFS has 14,680 stars and appeared on the Go daily list on 2026-11-05 with 39 stars gained and a best position of 14 that day; this is the only recorded snapshot, so it supports no trend claim. The more telling signal is the discussion record: it reached Hacker News in January 2021 with 219 points and January 2026 with 186 points, five years apart. In the 2026 thread, a commenter reports that the Sprites storage stack is built on a heavily modified JuiceFS with a rewritten SQLite metadata backend, while another describes moving away at Krea due to insufficient training performance and the constraint of placing the metadata store in a single location. Those experiences illustrate the design's central tradeoff: the metadata layer, not the object store, determines both performance and failure scope.