Circe: a JSON library for Scala that names its adopters
Yet another JSON library for Scala
At a glance
- What is it?
- The README of this Scala JSON library is not a tutorial, it is an adopter list with throughput figures attached: Criteo migrating 200k queries per second off Jackson, SoundCloud transforming 200 million events an hour, Twilio sending millions of messages a day.
- Who is it for?
- Circe is the JSON library for Scala codebases that treat parse failures as part of the type rather than an exception to catch, and the README supports that claim with numbers rather than adjectives: Criteo at 200k events per second off Jackson, SoundCloud at 200 million events an hour, TabMo above 100k per second, Ravel Law on tens of millions of legal opinions.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Scala, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 7, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The README is an adopter list, and the annotations carry the argument
The opening of this README is two sentences and then a list. The sentences say circe is a JSON library for Scala and Scala.js, and point to a guide for why circe exists and how to use it. Everything after that is a roster, starting with Abacus and Anduin Transactions and running through roughly ninety organizations to Zendesk.
What makes the list unusual is that many entries carry a throughput figure in parentheses rather than a bare logo. Criteo reports collecting 200,000 events per second from its banners, and links to a writeup about migrating a service to 200k QPS from Jackson to circe. SoundCloud reports transforming 200,000,000 JSON events every hour in MapReduce ETLs. TabMo reports parsing more than 100k events per second with Akka Stream and Spark. Twilio reports sending many millions of messages a day with circe and Akka. Chartboost reports hundreds of thousands of messages per second on its ad exchange.
Other entries describe workload shape instead of rate. Ravel Law uses circe to de/serialize data for search, analytics and visualization of tens of millions of legal opinions. Project September uses it to exchange and store data within the platform and serve data using GraphQL with Sangria. Spotify uses it for JSON IO in Scio. Connio is described as creating and managing digital twins with circe and Akka.
That combination of names and figures is the real documentation here. A reader trying to decide whether a JSON library holds up under load gets, unusually, actual numbers and the systems they were measured on.
Twelve sibling projects under the circe organization
The section headed 'Other circe organization projects' explains how the core library is meant to relate to its neighbours, and it is worth reading because it shows what the core does not do. The README asks people to get in touch on Gitter about hosting a circe-related project under the circe organization.
`circe-jackson` provides Jackson-backed parsing and printing for circe, which is the escape hatch when you want to reuse an existing Jackson setup rather than fight it. `circe-yaml` uses SnakeYAML to parse YAML 1.1 into circe's `Json`, so YAML becomes an input format rather than a second model. `circe-config` translates between HOCON, Java properties and JSON documents.
The streaming half is separate too: `circe-fs2` provides streaming JSON parsing and decoding built on fs2 and Jawn, and `circe-iteratee` does the same for iteratee.io. `circe-spray` supplies JSON marshallers for Spray. `circe-refined` builds encoders and decoders on Refined for compile-time validation of values. `circe-derivation` is described as experimental generic derivation with improved compile times, and `circe-benchmarks` exists for comparing circe against other JSON libraries on the JVM.
Under Related projects the README lists downstream consumers, including `akka-http-json` for Akka HTTP marshalling, `akka-stream-json`, `Argus` which generates models and codecs from JSON schemas, `borer` for reusing circe codecs with CBOR, and `circe-debezium`.
The pattern is consistent: circe core owns the model and the codecs, and anything platform-specific is a separate artifact. That is a deliberate modular choice, and it is why the artifact you depend on is small.
Release 0.14.16 is four decoder fixes and a security bump
The three recorded releases describe a library in maintenance mode with a functioning dependency pipeline. v0.14.16 came out on 2026-06-24 and its body names an important transitive security bump for Jawn alongside enhancements and bugfixes.
The four substantive changes are all decoding correctness. Scala 3 `ConfiguredDecoder` now caches the member names transformation, which is a performance fix in the generic-derivation path on Scala 3. A `NumberFormatException` when parsing leading-dot-zero decimals is fixed, so `.5` no longer throws where `0.5` parses. Errors are now accumulated in `Decoder#or` and `Decoder#either` with `decodeAccumulating`, which means a combined decoder reports every field problem instead of stopping at the first. And a wrong failure for `NonEmptyX` decoding on non-array inputs is fixed.
The dependency updates in the same release: jawn to 1.7.0, scalajs to 1.21.0, scodec-bits to 1.2.5 and scala-java-time to 2.7.0.
v0.14.15, published 2025-09-30, is almost entirely scala-steward bumps, and v0.14.14, published 2025-06-13, says outright that it is just dependency updates, mostly to exercise the new Sonatype Central release process. Read together, the three releases say the core API has not moved and the work is in keeping transitive dependencies current. That is the right shape for a library this widely depended on.
Two extra licence files at the root explain the code's ancestry
The tree carries `LICENSE`, `LICENSE.argonaut`, `LICENSE.ephox` and a `NOTICE` file. That trio is more informative than it looks. Circe is Apache 2.0 licensed, and the two extra licence files record code inherited from Argonaut, the earlier Scala JSON library, and from Ephox, the Scala port of Phil Bagwell's Cesante library.
This matters for a reader who arrives with a specific question about derived encoders or codec combinators, because that part of circe's design is not new invention so much as continuation. Circe's own public description in the repository metadata is candid about the crowded field: 'Yet another JSON library for Scala'.
The rest of the repository root shows a project with real process. There is `build.sbt`, a `project/` directory for sbt build definitions, a `modules/` directory holding the multi-module layout, and a `data/` directory. `docs/` holds documentation and `examples/` holds two runnable examples, `examples/sf-city-lots/` and `examples/todo-spray/`.
Tooling is pinned in files that name the tools: `.scalafmt.conf` for formatting, `.scalafix.conf` for lint rules, `.jvmopts` for the JVM build, `.scala-steward.conf` for automated dependency bumps, `.codecov.yml` for coverage reporting, and `.git-blame-ignore-revs` for mass reformatting commits. There is also `flake.nix` and `flake.lock` for a Nix development environment, `CODEOWNERS`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `DESIGN.md`.
That last file is the one to open before choosing the library, because it explains the reasoning rather than the usage.
Maven coordinates, a 2.13 badge and a branch named after the series
The Maven Central badge names `io.circe/circe-core_2.13` with a version prefix of 0.14, which settles the coordinate question and hints at the cross-build situation. Circe publishes per Scala version, so the artifact suffix changes with the Scala line you are on, and the Scala 3 artifacts exist alongside the Scala 2 ones. The v0.14.16 release notes reference Scala 3 `ConfiguredDecoder` behaviour, so the Scala 3 path is maintained rather than merely tolerated.
The default branch is `series/0.14.x`, not `main` or `master`. That is a deliberate signal: the branch is named for the release series it carries, so work on the next line would happen elsewhere. It also means the `0.14` prefix in the coordinates is not cosmetic. There is no 1.0, and the API you depend on today is the 0.14 API.
Project status: 2540 stars, 546 forks, 131 open issues, not archived, Apache 2.0. The repository was pushed on 2026-09-14, and the recorded v0.14.16 release is from June 2026, so the 0.14 line is the live one. The homepage is circe.io/circe and the guide linked from the README is at circe.github.io/circe.
With 131 open issues on a library this size, the fair reading is that the backlog is mostly edge cases around Scala 3 derivation, numeric parsing and platform behaviour rather than anything structural.
What Circe is good at, and where the alternatives still make sense
The honest case for circe is that its codecs are values. `Decoder` and `Encoder` compose as ordinary case classes, failure is returned as data rather than thrown, and the generic-derivation path removes the boilerplate that makes hand-written codecs in other libraries tedious. That is the design the guide at circe.github.io/circe exists to explain, and the README deliberately does not duplicate it.
The case against is equally concrete. If your Scala project already depends on Jackson, adding circe-jackson to bridge is cheaper than migrating, and the organisation hosts exactly that adapter. If you need JSON Schema generation from your model rather than codecs derived by hand, `Argus` is the tool in this ecosystem. If you want zero runtime dependency beyond the JDK, this is not that library.
The version history supports reading it as a stable choice. Three releases, all on the 0.14 line, with dependency bumps dominating and four targeted decoder fixes in the newest one. There is no migration note in any of the three release bodies.
The repository README will not tell you how to write your first decoder, and it is not trying to. It is trying to show you who runs this in production and at what rate, and to point you at the guide for everything else.
Editorial conclusion
Circe is the JSON library for Scala codebases that treat parse failures as part of the type rather than an exception to catch, and the README supports that claim with numbers rather than adjectives: Criteo at 200k events per second off Jackson, SoundCloud at 200 million events an hour, TabMo above 100k per second, Ravel Law on tens of millions of legal opinions. The current release is v0.14.16 from 2026-06-24, on a default branch named `series/0.14.x`, with the numeric prefix still signalling a pre-1.0 API that has been stable in practice for years. Start at the guide at circe.github.io/circe, add `io.circe:circe-core` for Scala 2.13 or the Scala 3 artifacts, and read the adopter annotations in the README to see what the library is actually being asked to do in production.
Frequently asked questions
What is circe and what is it used for in Scala?
Circe is a JSON library for Scala and Scala.js that decodes JSON into typed values and encodes them back out, with codecs written as ordinary case classes and decode failures returned as data rather than thrown exceptions. The repository metadata describes it plainly as 'Yet another JSON library for Scala'.
How do I add circe to a Scala project?
The Maven Central badge names the artifact as `io.circe/circe-core_2.13` with a version prefix of 0.14, so the group is `io.circe` and the artifact suffix follows the Scala version you build against. The README links the usage guide at circe.github.io/circe rather than repeating setup instructions.
What is the latest circe release and what did it fix?
v0.14.16, published on 2026-06-24, along with a transitive security bump for Jawn. The substantive changes were caching member names transformation in Scala 3 ConfiguredDecoder, fixing a NumberFormatException on leading-dot-zero decimals, accumulating errors in Decoder#or and Decoder#either via decodeAccumulating, and fixing a wrong failure for NonEmptyX on non-array input.
Who uses circe in production, and how much JSON are they moving?
The README lists roughly ninety adopters and annotates several with throughput. Criteo reports 200,000 events per second after migrating from Jackson, SoundCloud reports transforming 200,000,000 JSON events every hour in MapReduce ETLs, TabMo reports more than 100k events per second, Twilio reports many millions of messages a day, and Chartboost reports hundreds of thousands of messages per second.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/circe-circe)