BLAKE3: one hash function, four modes, and a Merkle tree underneath

Why a Merkle tree changes what a hash can do

BLAKE3 is described as an optimized instance of BLAKE2 plus the original Bao tree mode, and the tree is the interesting part rather than a detail. Because input is split into chunks that hash independently and combine upward, you can work across any number of threads and SIMD lanes at once. A SHA-2 implementation is a long dependency chain that resists parallel work; a BLAKE3 tree is a batch of independent subtrees that collapse at the end.

The same structure gives you two properties the README lists separately. Verified streaming means a Merkle root commits to the whole input, so chunk boundaries are recoverable and a partial file can be checked against a root it never fully hashed. Incremental updates work the same way: hash one chunk, reuse the result, and pay only for the changed part. A conventional hash has no notion of where a boundary lies, so both features require the tree.

The compression function itself is inherited, not new. That has a practical consequence for review. When BLAKE3 is described as fast, the interesting engineering is in the chunk scheduler and the vector code, not in the round function, and the repository separates the two so you can read each on its own.

Four modes from one algorithm with no variants

The README's claim of one algorithm with no variants is a design commitment worth understanding. Most families ship variants with different block sizes and digest lengths, which means a decision at design time and interoperability constraints downstream. BLAKE3 has one compression function and the mode is selected by how you call it.

The default 256-bit output behaves as an ordinary hash. `keyed_hash` takes a 256-bit key and gives you a MAC, and `derive_key` takes a context string plus key material to produce a subkey. Extended output comes from `finalize_xof`, so the same input can produce an arbitrary-length stream rather than a fixed digest.

// Hash an input all at once.
let hash1 = blake3::hash(b"foobarbaz");

// Hash an input incrementally.
let mut hasher = blake3::Hasher::new();
hasher.update(b"foo");
hasher.update(b"bar");
hasher.update(b"baz");
let hash2 = hasher.finalize();
assert_eq!(hash1, hash2);

The `derive_key` mode deserves the README's own caution about its context string. It should be hardcoded, globally unique and application-specific, with a suggested format of application, commit timestamp and purpose. Feeding it a password is the mistake: the mode is fast by design, which is exactly wrong for password hashing, and the README says so in a note that points at Argon2 instead.

Getting b3sum installed and timing it against OpenSSL

The command line utility is `b3sum`, published as a separate crate. Prebuilt binaries exist for Linux, Windows and macOS on the releases page, and macOS users need the unidentified developer workaround since the binaries are not notarised. If you already have Rust and Cargo, the crate installs with one command:

cargo install b3sum

If `rustup` did not put the binary on your `PATH`, the README points at `~/.cargo/bin`. Once it is available, the project suggests hashing something large to get a feel for the difference against SHA-256:

# Create a 1 GB file.
head -c 1000000000 /dev/zero > /tmp/bigfile
# Hash it with SHA-256.
time openssl sha256 /tmp/bigfile
# Hash it with BLAKE3.
time b3sum /tmp/bigfile

The README also makes a specific claim about `b3sum`: it uses multithreading by default and is an order of magnitude faster than something like `sha256sum` on typical desktop hardware. The benchmark chart on the README page is narrower than that sentence, being an example of 16 KiB inputs on a Cascade Lake-SP from 2019, and the paper carries the detailed numbers. Treat both as claims to check on your own hardware and your own input sizes rather than as a measurement you have inherited.

What the Rust crate configures at compile time

`Cargo.toml` in the repository is worth reading before you add the dependency, because the interesting choices are all in the feature flags. The default feature set is just `std`. Multithreading is off by default: the `rayon` feature adds `update_rayon` and, with `mmap`, `update_mmap_rayon`, and even with it enabled every other API stays single-threaded.

The SIMD story is split between dynamic detection and compile-time assumption. The x86 builds carry optimized implementations for SSE2, SSE4.1, AVX2 and AVX-512 with runtime CPU feature detection, and detection itself now uses the no-std-compatible `cpufeatures` crate rather than the `std` feature. NEON is different: `neon` is an opt-in flag that assumes support rather than detecting it, because detection is currently x86-only. The comment in `Cargo.toml` notes that AArch64 always has NEON while ARMv7 varies, and that the NEON implementation uses C intrinsics and therefore needs a C compiler.

Two flags behave the same way for WebAssembly. `wasm_simd` assumes the host supports the Wasm SIMD specification, with a note that not every implementation does and that this may become the default later. For a no-std target, turning `std` off drops the `std::io` traits and `Hasher::update_reader`, which is the usual reason to do it.

Three implementations and an explicit licence split

The repository ships three implementations on purpose, and the README tells you which to read for which job. The `blake3` Rust crate is the optimized one. The C implementation under `c/` mirrors it with the same SIMD work, x86 detection and optional multithreading, documented in its own README. The Rust reference implementation at `reference_impl/reference_impl.rs` is much smaller, has no SIMD and no threading, and is the one Section 5.1 of the paper discusses. If you want to understand the algorithm or port it to a language nobody has ported yet, that is the file to start from. Separate repositories host reference ports to C and Python.

Licensing is more nuanced than a single licence name, and the tree shows why: `LICENSE_A2`, `LICENSE_A2LLVM` and `LICENSE_CC0` all sit at the top level. `Cargo.toml` declares the Rust crate as `CC0-1.0 OR Apache-2.0 OR Apache-2.0 WITH LLVM-exception`. A dual option like that lets you pick whichever obligation suits you, with the LLVM exception there for linkage into GPL code. Read the files themselves before shipping a binary that embeds the C implementation.

The `test_vectors/test_vectors.json` file covers extended outputs, all three modes and a spread of input lengths, which makes it the fastest way to check that a port you just wrote agrees with everyone else's.

Where the release history shows real wear

Three releases in `Cargo.toml` and on the release list show the version line at 1.8.7, published 2026-08-20, and the changelog entries are more informative than version numbers usually are.

The 1.8.7 entry removes the `arrayref` dependency, with a one-line explanation that the crates.io owner was compromised. That is a supply chain response rather than a feature change, and it is the sort of note that tells you how the maintainers handle dependencies they did not write.

1.8.6 is a genuine correctness fix for file handling. `update_mmap` and `update_mmap_rayon` switched from `metadata` to `seek` to determine length and now tolerate `mmap` failures. The visible effect is that `b3sum` can memory map things that report length 0 in `metadata`, such as Linux block devices, and that hashing `NUL` files on Windows no longer errors unless you pass `--no-mmap` or redirect from `<`. 1.8.5 forcibly disables LTO when compiling C intrinsics from the Rust build, fixing a break on Arch Linux ARM.

None of this touches the algorithm, which is the point. A hash function's stability guarantee matters more than its release cadence, and BLAKE3's is protected by being specified in the Community Cryptography Specification Project at c2sp.org. It is not a NIST standard, and the README does not claim to be one.

Editorial conclusion

BLAKE3 fits content addressing, build caching and file integrity work where you want SHA-256's shape with more speed and parallelism, and it is a reasonable default for new internal systems. Two boundaries are worth holding onto. It is not a password hash, and Argon2 is the README's own recommendation for anything credential-derived, while fixed-output use such as Git's object naming depends on preimage resistance rather than the verified-streaming mode that sets it apart. Start by installing `b3sum` and hashing the test vectors in `test_vectors/`, then read section 5.1 of the paper and the `reference_impl/reference_impl.rs` file before writing a port.

Frequently asked questions

Official sources

1. BLAKE3-team/BLAKE3 on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases