# Nydus: an on-demand filesystem where the image is an index, not a tarball

> Nydus turns an OCI image into a RAFS format with a separate metadata part and a data part, so a container pulls only the chunks it reads. The trade is a conversion step and a daemon in the read path, and the v3 line is still on beta tags.

**dragonflyoss/nydus** — Nydus - a reliable, high-performance on-demand load filesytem framework for container image and data distribution.

- Repository: https://github.com/dragonflyoss/nydus
- Website: https://nydus.dev/
- Stars: 1,688 · Forks: 282
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/dragonflyoss-nydus

## The image splits into an index and a blob store

Nydus implements a content-addressable filesystem on what it calls the RAFS format, layered on top of the existing OCI image specification. The README frames the goal as improving container launch speed, image space and network bandwidth efficiency, plus data integrity.

The structural change is what the `nydus-image` tool does. It converts a single layer of an OCI format image into Nydus format and generates a metadata part file and a data part file separately. That separation is the mechanism behind on-demand loading: the metadata part describes the filesystem tree, and the data part holds the chunks the tree refers to. A container can therefore start with only the metadata and fetch content as reads arrive.

The stated benefit is second-level container startup and millisecond-level loading for function computation code packages, with the caveat the README itself supplies, that the advantage grows as OCI image size increases. The bundled chart plots cold startup elapsed time on containerd against image size and shows the gap widening.

The code is written in Rust, and the licence in `Cargo.toml` is `Apache-2.0 OR BSD-3-Clause`, a choice that lets you take either term.

## Three binaries and a client, each with one job

The tool surface is small enough to describe precisely, which is unusual for a project of this size.

`nydusd` is the user-space daemon. It processes all fscache and FUSE messages from the kernel and parses Nydus images to fulfil those requests. `nydus-image` is the converter described above. `nydusify` is the pipeline tool: it pulls an OCI image down, unpacks it, invokes `nydus-image create` to convert the image, then pushes the converted image back to the registry and to data storage. `nydusctl` is the daemon client, described as the `nydus-image inspect` counterpart, used to query the daemon's working status and metrics and to configure it.

All three binaries are declared in `Cargo.toml` with explicit paths, `nydusctl` at `src/bin/nydusctl/main.rs`, `nydusd` at `src/bin/nydusd/main.rs` and `nydus-image` at `src/bin/nydus-image/main.rs`, alongside a library named `nydus` rooted at `src/lib.rs`. Internal crates include `nydus-api`, `nydus-builder`, `nydus-rafs` and `nydus-service`, so the format and service layers are separable.

Two components sit outside the core. `nydus-overlayfs` is a containerd mount helper that tweaks overlayfs mount options so Nydus prerequisites can be passed to a VM-based runtime, and `nydus-backend-proxy` is a simple HTTP server that serves a local directory as a blob backend for `nydusd`, which is how you develop without a real object store.

## Where the data comes from, and the runtimes it plugs into

Storage backends are listed as Registry, OSS, NAS, shared disk and a P2P service. The P2P option links to the Dragonfly project at `d7y.io`, which is worth pausing on: it means Nydus is not tied to a single distribution mechanism and can sit behind a peer-to-peer layer instead of pulling every layer from a registry.

On the runtime side, the README states support for runC and Kata, and it also points at Confidential Containers and at vulnerability scanning capabilities. Those are two different claims. Confidential container support is about running Nydus inside a trusted execution environment, which the `nydus-overlayfs` mount helper exists to support. Vulnerability scanning is about being able to inspect image contents in the Nydus format, which follows from having the format documented.

Image compatibility is broader than the Nydus format itself. There is a document on Nydus Zran, described as OCI image compatibility, and native support for eStargz images through the containerd stargz snapshotter.

Runtime installation is documented elsewhere, not here. The README links a Kubernetes quick start in the nydus-snapshotter repository and a nerdctl quick start in the nerdctl repository, which is a reasonable division since Nydus is consumed through those integrations rather than wired up by hand.

## The performance claims, and where they stop

Two claims in the README deserve scrutiny rather than adoption.

The first is that Nydus images significantly outperform OCI images on container cold startup elapsed time on containerd, particularly as OCI image size increases. The qualification does most of the work. On a small image the difference between downloading everything and downloading a metadata index plus the chunks you touch is small, and the conversion overhead is not zero. 

The second is the security claim, described as end to end data integrity check with supply chain attacks detectable and avoidable at runtime. Content addressing does give you per chunk verification, and the chunk deduplication across layers and images is real. What it does not by itself give you is a signature over the image manifest in a format your runtime enforces, so treat the integrity property as chunk-level and verify the trust chain separately.

The same caution applies to the POSIX compatibility claim, which is achieved through in-kernel EROFS or FUSE filesystems together with overlayfs. That is a real compatibility surface, and it is also the most likely place to hit surprises with edge cases in a filesystem you did not write.

## Building: platform-dependent feature flags in the Makefile

The repository builds with Cargo through a Makefile, and the Makefile is where the platform matrix shows up.

The static target defaults to the host triple, and on Linux it adds the feature flags `virtiofs` and `block-uffd` to the common Cargo arguments. On Linux the static target stays as the musl triple except on ppc64le, where it becomes `powerpc64le-unknown-linux-gnu`, and on riscv64, where it becomes `riscv64gc-unknown-linux-gnu`. On Darwin it becomes `x86_64-apple-darwin` on amd64 and `aarch64-apple-darwin` on arm64, and `nydus-blobfs` is excluded from the package list there.

```bash
make release
```

That exclusion is the clearest statement in the repository about what Nydus is for. Blobfs is the in-kernel path, and if you are building on macOS you cannot get it. `block-uffd` in the Linux feature flags points at the same area, since userfaultfd handling is how the kernel and daemon coordinate page faults for the FUSE path.

Coverage instrumentation is built in through `LLVM_PROFILE_FILE` and a `GRCOV_ARGS` variable that ignores Rustup and Cargo directories, and defining `ENABLE_DEBUG` switches off release optimization while wiring in the debug binaries for the daemon and the builder.

The repository is not pure Rust either: it has a `go.work` file, a `clib/`, a `builder/` and a `storage/` directory, so cross-language glue is part of the design.

## Against stargz and against the stargz snapshotter

The direct comparison is with stargz, and Nydus is already integrated with it, which makes the comparison concrete.

Nydus supports eStargz images natively through the containerd stargz snapshotter. Nydus offers in-kernel EROFS or FUSE filesystems together with overlayfs. The in-kernel option is the one that avoids userspace on the hot read path, which is where a Rust daemon and the claim about memory and CPU consumption come from.

The other comparison is against doing nothing, which means a containerd snapshotter on plain OCI layers. That path has no conversion step, no daemon and no new format, and it is entirely adequate for workloads with small images or with long-lived containers that amortise their startup. Nydus wins when startup happens constantly and the image is large, which is the serverless and scale-to-zero case.

## Conclusion

Adopt Nydus if cold container startup on large OCI images is a measured problem for you and you can afford a conversion step plus a daemon in the mount path. Do not adopt it on the strength of the README's benchmark image alone, because the gains grow with image size and will be small for images that already start quickly. Verify first which version you are pinning, since the recent tags are v3.0.0-alpha.3, v3.0.0-beta.1 and v3.0.0-beta.2 rather than a final v3 release.

## FAQ

### What is Nydus and what format does it use?

Nydus implements a content-addressable filesystem on the RAFS format, enhancing the OCI image specification. The `nydus-image` tool converts an OCI layer into a metadata part file and a data part file, which lets containers load chunks on demand.

### What are the main Nydus tools?

`nydusd` is the user-space daemon handling fscache and FUSE messages, `nydus-image` converts OCI layers into Nydus format, `nydusify` pulls, converts and pushes images, and `nydusctl` is the client used to query daemon status and metrics and to configure it.

### Where can I find instructions to run Nydus on Kubernetes or with nerdctl?

The README links a Kubernetes quick start in the nydus-snapshotter repository and a nerdctl quick start in the nerdctl repository. Installation and troubleshooting notes are in the project FAQ wiki.

### Does Nydus support eStargz images?

Yes. The README lists native eStargz image support through the containerd stargz snapshotter, and separately documents OCI image compatibility through Nydus Zran.

### What licence does Nydus use?

The `Cargo.toml` declares the licence as `Apache-2.0 OR BSD-3-Clause`, so you may choose either term. The repository also carries `LICENSE-APACHE` and `LICENSE-BSD-3-Clause` files at the root.

### Is Nydus v3 released?

The recent tags are v3.0.0-alpha.3 on 2026-09-21, v3.0.0-beta.1 on 2026-09-23 and v3.0.0-beta.2 on 2026-10-10, so the v3 line is still in beta rather than final.

## Sources

- [dragonflyoss/nydus on GitHub](https://github.com/dragonflyoss/nydus)
- [License: Apache-2.0](https://github.com/dragonflyoss/nydus/blob/master/LICENSE)
- [Project website](https://nydus.dev/)
- [README](https://github.com/dragonflyoss/nydus/blob/master/README.md)
- [Releases](https://github.com/dragonflyoss/nydus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dragonflyoss-nydus