Skip to content
Get packs

Guide · Open source

How to use 3FS: clone, build and run the file system

Updated · written with AI from the project's own documentation and checked against our catalogue data

3FS (Fire-Flyer File System) is an open-source distributed file system from deepseek-ai, written in C++ and released under the MIT licence. It spreads files across many storage machines and presents them to applications as one shared storage layer, aimed at AI training, data preparation, checkpointing and LLM inference caching. This guide walks through what you need, how to fetch and build the source, and where to go next to run a test cluster.

3FSdeepseek-ai/3FS · ★ 10.4k · MIT

Quick start

  1. 1Check your system. Confirm you run a supported OS (Ubuntu 20.04/22.04, openEuler, OpenCloudOS or TencentOS) or plan to use a Docker build image.
  2. 2Install dependencies. Install the package list for your distribution, then add libfuse 3.16.1+, FoundationDB 7.1+ and Rust 1.75.0+ (1.85.0 recommended).
  3. 3Clone the repository. Run git clone on the deepseek-ai/3fs repository and change into the 3fs folder.
  4. 4Fetch submodules and apply patches. Run git submodule update --init --recursive and then ./patches/apply.sh.
  5. 5Choose a shuffle method. Pick g++10 or g++11 for -DSHUFFLE_METHOD, matching your existing cluster or fixing it for a new one.
  6. 6Configure and build. Run the cmake configure command into the build folder, then cmake --build build -j 32.
  7. 7Run a test cluster. Follow deploy/README.md to set up a test cluster.

What 3FS is and who it suits

3FS uses modern SSDs and RDMA networks for high throughput and exposes a standard file interface, so applications do not need a new storage API. The README describes features such as CRAQ-based strong consistency, stateless metadata services backed by a transactional key-value store like FoundationDB, and random access to training samples across compute nodes.

  • Large AI training clusters that need shared, high-throughput storage
  • Data pipelines that write many intermediate files across compute nodes
  • Infrastructure teams evaluating storage for LLM inference caching
  • Operators comfortable building and running a distributed system from source

Check the prerequisites before you start

The README lists supported systems as Ubuntu 20.04 or 22.04, openEuler, and OpenCloudOS or TencentOS, or you can use the Docker build images. You also need CMake, a C++ toolchain (clang-14, or gcc 10 or 11+), libfuse 3.16.1 or newer, FoundationDB 7.1 or newer, and a Rust toolchain at least 1.75.0 (1.85.0 or newer recommended).

  • libfuse 3.16.1 or newer
  • FoundationDB 7.1 or newer
  • Rust toolchain: minimum 1.75.0, recommended 1.85.0 or newer
  • CMake and a C++ toolchain (clang-14 or gcc 10/11+)

Install the system dependencies

The README gives a separate package list for each supported distribution. Use the block that matches your OS. The Ubuntu 20.04 list, for example, includes clang-14, gcc-10 and libboost1.71-all-dev. The list below is the Ubuntu 20.04 command from the README; for other systems, copy the matching block from the source README.

  • Ubuntu 20.04, Ubuntu 22.04, openEuler 2403sp1 and OpenCloudOS 9 / TencentOS 4 each have their own package list in the README
  • Install libfuse, FoundationDB and Rust separately, using the links in the README
apt install cmake libuv1-dev liblz4-dev liblzma-dev libdouble-conversion-dev libdwarf-dev libunwind-dev \ libaio-dev libgflags-dev libgoogle-glog-dev libgtest-dev libgmock-dev clang-format-14 clang-14 clang-tidy-14 lld-14 \ libgoogle-perftools-dev google-perftools libssl-dev libclang-rt-14-dev gcc-10 g++-10 libboost1.71-all-dev build-essential

Clone the repository and check out submodules

Clone the source from GitHub, then initialise its submodules and apply the patches shipped with the repository.

git clone https://github.com/deepseek-ai/3fs cd 3fs git submodule update --init --recursive ./patches/apply.sh

Build 3FS with CMake

Configure the build in a folder called build, then compile. The README's example uses clang-14. You must replace <method> with g++10 or g++11, depending on your environment, because binaries built with different compiler versions may be incompatible due to the historical use of std::shuffle.

Existing clusters should use the method matching the compiler that deployed them. For a new cluster you can pick either, but then keep the same setting for all future builds. The README also lists Docker build images for TencentOS-4 and OpenCloudOS-9 as an alternative to a local build.

  • Existing clusters: match the compiler version used to deploy them
  • New clusters: choose g++10 or g++11 and stick with it for all future builds
cmake -S . -B build \ -DCMAKE_CXX_COMPILER=clang++-14 -DCMAKE_C_COMPILER=clang-14 \ -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DSHUFFLE_METHOD=<method> cmake --build build -j 32

Run a test cluster

The README does not walk through cluster setup itself. It points to the setup guide in deploy/README.md, which describes how to run a test cluster. Read that guide before attempting a deployment, since 3FS is designed for multi-node setups with SSDs and RDMA networking.

  • Setup Guide: deploy/README.md
  • Design notes: docs/design_notes.md
  • USRBIO API reference: src/lib/api/UsrbIo.md

What people use it for

  • Shared storage for a large AI training cluster across many compute nodes
  • Writing and organising intermediate outputs from data analytics pipelines
  • Random access to training samples without prefetching or shuffling datasets
  • Caching key-value data for LLM inference as a lower-cost alternative to DRAM

Frequently asked questions

Is 3FS free to use?

3FS is released under the MIT licence, as shown in the repository badge and licence file. The licence allows you to use and modify the code, but the README does not describe any paid product or support plan.

What are the requirements for 3FS?

The README lists Ubuntu 20.04/22.04, openEuler, OpenCloudOS or TencentOS (or Docker build images), CMake, a C++ toolchain, libfuse 3.16.1 or newer, FoundationDB 7.1 or newer, and Rust 1.75.0 minimum. The design targets SSDs and RDMA networks in clusters, so a single laptop is not the intended setup.

Can I install 3FS with a package manager?

The README only describes building from source, with optional Docker build images for TencentOS-4 and OpenCloudOS-9. It does not list packaged binaries, so plan on a clone-and-build process.

Why does 3FS need a SHUFFLE_METHOD setting?

Binaries built with different compiler versions, such as g++10 and g++11, may be incompatible because of the historical use of std::shuffle. Setting -DSHUFFLE_METHOD to a consistent value keeps builds compatible with your cluster.

How does 3FS compare with Lustre, CephFS, JuiceFS or BeeGFS?

The README does not compare 3FS with these projects, so this guide cannot rank them. Its own focus is on high-throughput AI workloads with a standard file interface, and the README reports benchmark results for its own clusters only.

Is 3FS suitable for a simple file share?

No. The README positions 3FS for large deployments that need SSDs and RDMA networking, so it is not designed for individuals or small projects that just want a simple shared folder.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

3FS suits teams running large AI training or inference clusters who can build and operate a distributed system from source. If you want a simple file share or a packaged product with support, pick a different tool, since the README describes only build-from-source and Docker build images.

Install options & downloads