The Rust storage stack.
V3 documentation · Examples · Migration guide · Changelog
Read, inspect, edit and build filesystems and disk images in pure Rust. Hadris
supports hosted tools, bootloaders, kernels and embedded firmware, with std,
alloc and allocation-free configurations and synchronous or asynchronous I/O.
Use one format crate, or the umbrella crate to detect and open multiple formats
through a shared filesystem API.
Release candidate: V3 3.0.0-rc.2
is the current V3 candidate, with development on main. Stable: V2 2.5.0,
with maintenance on v2.
The migration guide covers the API and CLI changes.
| Format | Read | Create or edit | Crate |
|---|---|---|---|
| FAT12, FAT16, FAT32 | Files, directories, VFAT long names | Edit, format, check | hadris-fat |
| exFAT | Files and directories | Edit, format, check | hadris-fat |
| ISO 9660 | Primary, Rock Ridge, Joliet and enhanced trees | Image authoring, sessions, El Torito and hybrid boot | hadris-iso |
| UDF | Mastered volumes | Image authoring and ISO/UDF bridges | hadris-udf |
| CPIO | newc, CRC, odc and old binary archives | Streaming newc, CRC and odc writers | hadris-cpio |
| MBR and GPT | Partition tables and recovery copies | Partition tables and whole-disk layouts | hadris-part |
| NTFS and APFS | Preview readers | Read-only | hadris-ntfs, hadris-apfs |
Once RC2 is published, install its CLI with cargo-binstall:
cargo binstall hadris-cli --version 3.0.0-rc.2
hadris --helpOr compile it using Rust 1.88 or newer:
cargo install hadris-cli --version 3.0.0-rc.2 --locked
hadris --helpInspect an existing image, or create one from a directory:
hadris detect disk.img
hadris fat ls disk.img
hadris iso create ./files -o image.iso --joliet --rock-ridge
hadris iso extract image.iso -o extractedThe hadris command has fat, iso, udf, cpio, apfs and detect
subcommands. fat handles FAT and exFAT; udf bridge authors hybrid optical
images. Image creation refuses an existing output unless --force is supplied;
extraction refuses to replace existing files.
For a self-contained source example that creates, detects and extracts FAT, exFAT, ISO and UDF images in a temporary directory:
git clone https://github.com/hxyulin/hadris.git
cd hadris
cargo run --locked -p hadris-example-extractUse the Rust libraries
The following dependency recipe selects V3 3.0.0-rc.2 once published.
Until then, use a workspace checkout of main.
One dependency reaches the format drivers and the shared I/O, device and
filesystem APIs. For a hosted FAT application:
[dependencies.hadris]
version = "3.0.0-rc.2"
default-features = false
features = ["std", "sync", "fat"]Specify the prerelease version explicitly; version = "3" does not select RC2.
For development snapshots, use a Git dependency pinned to a reviewed rev.
Use hadris::fat, hadris::fs, hadris::storage and hadris::io; enabling
only fat does not add other formats. Add write for FAT formatting, or
detect and part for unknown/partitioned images. Individual crates remain
available when their versions and dependencies should be managed separately.
For allocation-free ISO reading use features = ["sync", "iso"]; for
allocation-free embedded FAT use ["sync", "fat"]. Keep defaults disabled.
The shared FAT driver instead needs ["alloc", "sync", "fat"] without std.
cargo run --locked -p hadris-example-migrate-v3The embedded guide and
firmware examples cover the APIs without an allocator.
For hosted use, hadris-fs provides FileSystem, Volume,
file handles and tree operations. The
async guide covers asynchronous use and explicit
close/sync. Add alloc to the ISO crate for image writing and sessions.
hadris-io defines portable I/O; hadris-storage supplies block devices, slices, caching and read-ahead; hadris-fs supplies the shared filesystem and image-tree APIs. Format crates retain their native operations, and hadris re-exports the stack with detection and opening.
Sync and Send async APIs share implementations generated by
hadris-macros. The
crate guide explains package selection and features;
the V3 design records the API rules.
The RC2 async device migration guide describes the unified local/Send device contract and compatibility paths.
Public API compatibility uses cargo-semver-checks, supported by feature-tier
builds, contract tests and the non-exhaustive lint. Format qualification uses
independent raw-image oracles and external implementations, including mtools,
dosfstools, xorriso, libarchive, udftools and native OS readers. See the
FAT, ISO and
UDF profiles for results and coverage boundaries.
NTFS and APFS native APIs remain previews. Optional APFS software unlocking
uses the encryption feature; Apple-silicon hardware FileVault needs separate
support. Known issues document remaining correctness and
durability limits. Performance measurements record
workload, I/O and memory tradeoffs rather than a universal speed claim.
CONTRIBUTING.md covers the toolchain, tests, CI and PR workflow. Use the repository's Nix shell for external image tools and prek hooks:
nix develop
prek install
cargo test --workspace --lockedRunnable examples, the tooling index and the fuzz harness provide focused entry points. Repository conventions for coding assistants are in AGENTS.md.
Hadris is available under the MIT license.