# sonic-rs: a SIMD JSON library for Rust that skips the tape

> sonic-rs is a Rust JSON library from the CloudWeGo team that uses SIMD to parse and serialize, and it builds typed values directly instead of going through an intermediate tape. It pays for that speed with a build requirement: the crate needs target-cpu=native and it falls back to a slower path off x86_64 and aarch64.

**cloudwego/sonic-rs** — A fast Rust JSON library based on SIMD.

- Repository: https://github.com/cloudwego/sonic-rs
- Website: https://crates.io/crates/sonic-rs
- Stars: 937 · Forks: 75
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudwego-sonic-rs

## A JSON library that parses straight into the Rust type you want

sonic-rs is a JSON parser and serializer for Rust, published on crates.io and maintained by the CloudWeGo team. Its stated purpose is speed, and the mechanism behind that speed is SIMD, but the design choice that shapes the whole library is architectural. The README states that sonic-rs directly parses JSON into a Rust struct with no temporary data structures, while simd-json in Rust first parses the JSON into a tape and then parses the tape into the struct. That difference is where the memory traffic and the allocation count go. The library targets two groups: services that parse large JSON payloads on x86_64 or aarch64 servers, and developers who want serde-compatible behaviour with a different implementation underneath. It also supports the untyped path, sonic_rs::Value, for documents whose shape is not known in advance, and a family of helpers for pulling fields out of JSON without a full typed parse.

## target-cpu=native is a hard requirement, not a tuning knob

The README is unusually direct about the build. It says faster on x86_64 or aarch64, and that other architectures fall back and may be much slower. To ensure that SIMD instructions are actually used, you need to add the rustflags -C target-cpu=native and compile on the host machine, and the README says Rust flags can be configured in Cargo config at .cargo/config.toml. Two consequences follow. First, a prebuilt binary or a container image built on different silicon will not get the fast path, so the build has to happen on the machine that runs it. Second, because target-cpu=native tunes for the build host, the resulting artifact is tied to that host's CPU features, which is exactly what you want for a service deployed onto your own fleet and exactly what you do not want for a binary shipped to unknown hardware. The library does run on stable Rust now, an earlier requirement for nightly that the README marks as struck through.

## The feature list is small and mostly about typed access

The README lists six capabilities. Serde support lets you deserialize into a Rust struct as serde_json and serde do. Untyped parsing and serialization cover sonic_rs::Value, which the README notes can be mutable. Field extraction is offered as a way to get specific fields from a JSON, and JSON can also be walked as a lazy array or object iterator. The type set includes LazyValue, Number and RawNumber, the last described as just like Golang's JsonNumber, and these are available in default. Floating point parsing precision is said to match Rust std in the default configuration. Two optional Cargo features extend that. arbitrary_precision switches Value parsing to an arbitrary precision number representation so JSON numbers serialize without loss of precision, and sort_keys sorts the keys when serializing a Value. Both are off by default, since the default feature set in Cargo.toml is empty.

## The untyped document is an arena where objects are arrays

The Value representation explains why the untyped benchmarks look the way they do. The README states that sonic-rs uses a memory arena for the whole document, which results in fewer memory allocations and better cache behaviour, and it also gives the document mutability. Then there is the structural choice: the JSON object in sonic_rs::Value is an array, and sonic-rs does not build a hashmap. So there is no hashing cost per key on the way in, and lookups are over an ordered list instead of a hash table. The trade-off is real and the README does not hide it. A document with many keys and repeated lookups by name will pay for scanning an array rather than hashing, and if you mutate a Value repeatedly you are working against an arena layout designed for bulk parsing. For the pattern the library is built around, reading a document once and pulling a few fields out, that trade is worth it. For repeated random access by key, the answer depends on your data shape.

## SIMD is used in four places, not everywhere

The README is careful about where the vector work actually happens. sonic-rs does not use the two-stage SIMD algorithms from simd-json, and instead applies SIMD in four scenarios: parsing and serializing long JSON strings, parsing the fraction part of float numbers, getting a specific element or field from JSON, and skipping whitespace while parsing. That list is narrower than the marketing around SIMD JSON parsers usually suggests, and it also explains the performance profile. Long strings and whitespace skipping are where a vectorised byte scan pays off most directly. Deeply nested short documents gain less. The README points to docs/performance.md for more detail on the optimisation work, and the top level of the repository shows the implementation split: src for the main crate, sonic-simd for the SIMD layer, sonic-number for number handling, plus a fuzz directory, a bindings directory and a benchmarks directory. The crate depends on ahash, bumpalo for the arena, bytes, faststr, itoa, simdutf8, thiserror and serde with the rc and derive features.

## Running the benchmarks yourself, and the version in the README

Two benchmark suites are documented, and both can be run locally. The struct benchmark parses into a typed struct with no unknown fields in the input, using test data from the json-benchmark project:

```bash
cargo bench --bench deserialize_struct -- --quiet
```

The untyped benchmark parses into a document instead:

```bash
cargo bench --bench deserialize_value -- --quiet
```

The README reports the environment as an x86_64 Intel Xeon Platinum 8260 at 2.40GHz, with AArch64 numbers kept in a separate document at docs/benchmark_aarch64.md. One caveat for anyone following along: the dependency snippet in the README still shows sonic-rs = "0.3", while the Cargo.toml in the repository declares version 0.5.10. Adding the crate as the README prints it will pin you to an old release. The manifest is the place to read the current version. The repository also ships a migration guide at docs/serdejson_compatibility.md for users moving from serde_json, and a separate note for Golang users who want to drive the library.

## The sanitize feature is a debugging tool with a stated price

There is one feature the README asks you to think hard about. If your program uses the LLVM sanitizer, you should enable the sanitize feature to avoid false positives. The same line warns against enabling it in production, because it causes 30 percent performance loss in serialize. That is the only performance figure the README attributes to a specific configuration rather than to a benchmark table, and it matters because sanitizers usually appear in CI and test builds, while the same crate and feature set often ships to production from the same pipeline. Enabling sanitize unconditionally means either paying that serialize cost in production or maintaining two feature configurations. The last released versions are v0.5.10 and v0.5.9, both dated 2026-09-11, with v0.5.8 from 2026-03-25 behind them. There is a ROADMAP.md in the repository, but the README does not summarise it, and the roadmap is the file to read if you need to judge the direction of the project.

## Conclusion

sonic-rs earns its place in a service whose JSON parsing shows up in profiles, on x86_64 or aarch64 hardware, where you control the build flags and can compile on the host machine. It is the wrong choice for a library that must run on arbitrary CPUs, for a WASM target, or for a team unwilling to set -C target-cpu=native. Verify first that your build actually compiles with that flag, that the fallback path on your architecture is acceptable, and that the sanitize feature stays off in production because the README puts its serialize cost at 30 percent. The licence field on the repository says Apache-2.0, the current manifest version is 0.5.10, and the last push was on 2026-10-11.

## FAQ

### Does sonic-rs require nightly Rust?

No. The README marks the nightly requirement as struck through and states that stable Rust is supported now. It does require the rustflags -C target-cpu=native and compiling on the host machine if you want SIMD instructions to be used.

### What does the sanitize feature do in sonic-rs and what does it cost?

It is recommended when your program uses the LLVM sanitizer, to avoid false positives. The README says it causes 30 percent performance loss in serialize, so it should not be enabled in production.

### How does sonic-rs differ from simd-json when parsing into a struct?

According to the README, simd-json in Rust first parses the JSON into a tape and then parses the tape into a Rust struct, while sonic-rs parses the JSON into the struct directly with no temporary data structures.

### Is sonic-rs usable on architectures other than x86_64 and aarch64?

The README says other architectures use a fallback that may be much slower. It also states that the crate falls back on other architectures, so it still compiles, but the speed advantage is specific to those two families.

## Sources

- [cloudwego/sonic-rs on GitHub](https://github.com/cloudwego/sonic-rs)
- [License: Apache-2.0](https://github.com/cloudwego/sonic-rs/blob/main/LICENSE)
- [Project website](https://crates.io/crates/sonic-rs)
- [README](https://github.com/cloudwego/sonic-rs/blob/main/README.md)
- [Releases](https://github.com/cloudwego/sonic-rs/releases)

---

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