Hadris

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 release candidate, which the recipes below use. 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

Quickstart

Install the CLI with cargo-binstall:

cargo binstall hadris-cli --version 3.0.0-rc.2
hadris --help

Or compile it using Rust 1.88 or newer:

cargo install hadris-cli --version 3.0.0-rc.2 --locked
hadris --help

Inspect an existing image, or create one from a directory:

hadris detect disk.img
hadris ls disk.img --partition 1
hadris fat ls disk.img
hadris iso create ./files -o image.iso --joliet --rock-ridge
hadris iso extract image.iso -o extracted

The hadris command has fat, iso, udf, cpio, apfs and detect subcommands, and ls, cat, extract and stat for any filesystem it detects, on a whole image or one partition. 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-extract

Use the Rust libraries

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 a release candidate. 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-v3

The 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.

Architecture

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; Principles and features states the API principles and feature rules.

The async device guide describes the unified local/Send device contract.

Compatibility and qualification

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 remain previews: hadris-ntfs and hadris-apfs carry 3.x versions but are outside the 3.x stability promise, and may break in a minor release (pin them with ~3.0). The umbrella reaches them only through its unstable-ntfs and unstable-apfs features. See stability. 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

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 --locked

Runnable examples, the tooling index and the fuzz harness provide focused entry points. Repository conventions for coding assistants are in AGENTS.md.

License

Hadris is available under the MIT license.