Moka: a concurrent Rust cache with TinyLFU admission and LRU eviction

What Moka solves, and who it is for

Moka is a cache library for Rust that wraps a hash map with an entry replacement algorithm, so the map stays bounded instead of growing with every key inserted. The README describes it as "a fast, concurrent cache library for Rust", inspired by Caffeine for Java. Retrievals run with full concurrency, and updates are expected to run highly concurrently as well.

The intended user is a Rust service that repeatedly computes or fetches the same values. The README lists two production cases: crates.io uses Moka in its API service to reduce load on PostgreSQL, and reports cache hit rates of about 85% for the high-traffic download endpoint; aliyundrive-webdav uses it to cache remote file metadata on home routers, including 32-bit MIPS and ARMv5TE devices. That second case matters because it shows the library is not limited to server hardware.

Moka is not the right default for every Rust program. The README states plainly that Moka "is a complex software and can be overkill for your use case", and points at Mini Moka or Quick Cache when a simpler cache fits.

TinyLFU admission, LRU eviction, and the two cache flavours

The mechanism is a hash map plus a replacement policy. Admission is controlled by a Least Frequently Used policy; eviction is controlled by a Least Recently Used policy. The README links to a wiki page for the details and benchmark results of this combination, and calls the resulting hit ratio near optimal. In practice this means a newly seen key does not immediately displace a frequently used one, which is the failure mode of a plain LRU cache under a scan-heavy workload.

Bounding is best effort. The README says all caches "perform a best-effort bounding of a hash map", so you should not treat the maximum entry count as a hard memory ceiling. A cache can be bounded by the maximum number of entries, or by the total weighted size of entries, which lets one large value count for more than one small one.

There are two cache flavours behind Cargo features. The sync feature enables moka::sync::{Cache, SegmentedCache} for sharing across OS threads. The future feature enables moka::future::Cache, which is futures aware and pulls in async-lock, event-listener and futures-util. Expiration supports time to live, time to idle and per-entry variable expiration, and an eviction listener callback fires when an entry is removed.

Installing Moka and writing a first sync cache

Moka is published on crates.io as moka, and the Cargo.toml in the repository declares the package with version 0.12.16 and an empty default feature set, so the sync or future feature has to be enabled explicitly. The README's usage section lists a synchronous cache example and an asynchronous cache example, and the repository ships matching files under examples/.

Enabling the sync feature in your own manifest follows the feature list in Cargo.toml:

[features]
sync = []
future = ["dep:async-lock", "dep:event-listener", "dep:futures-util"]

Those are the two feature definitions exactly as the manifest declares them. With sync enabled, the README's synchronous cache example is the starting point; the repository file examples/basics_sync.rs is the runnable version of it, and examples/basics_async.rs is the equivalent for moka::future::Cache. Alongside those two, the examples directory contains counter, bounded_counter, append_value, try_append_value, cascading_drop, eviction_listener, jittered_expiry_policy, reinsert_expired_entries and size_aware_eviction examples, most in both sync and async forms. Copying the closest one is faster than assembling a cache from the API docs.

Where Moka is the wrong tool

The README's own comparison table is the most useful limitation list. Moka has no non-concurrent cache; Mini Moka and Quick Cache both do, and a single-threaded cache avoids the synchronization cost entirely. Moka also does not have a small dependency tree, and it does not have small overhead compared to a concurrent hash table, while Quick Cache claims both. If your cache sits on a hot path where every nanosecond of bookkeeping is visible, that trade-off is the whole decision.

Platform support is another hard boundary. The README says Moka should work on most 64-bit and 32-bit platforms where Rust std is available with threading support, but that WebAssembly and WASI targets are not supported. If you are compiling a Rust crate to Wasm, this library is out of scope.

Finally, the project has a history of breaking changes. The README carries a note that v0.12.0 had major breaking changes on the API and internal behavior, and points to MIGRATION-GUIDE.md. Upgrading across that boundary is real work, not a version bump.

Moka compared with Mini Moka and Quick Cache

Mini Moka is the smaller sibling from the same project. Its README comparison shows it keeps the thread-safe sync cache and TinyLFU, but drops the async cache, per-key atomic insertion via get_with, per-entry variable expiration, the eviction listener and the lock-free concurrent iterator. It uses a lock-per-shard iterator instead, and it has a small dependency tree. If you only need a bounded sync cache and want fewer dependencies, Mini Moka covers that and nothing more.

Quick Cache takes a different replacement approach: S3-FIFO rather than TinyLFU, according to the same table. It offers both sync and async thread-safe caches, per-key atomic insertion, an eviction listener through a lifecycle hook, and a lock-per-shard concurrent iterator. What it does not have is cache-level time-to-live or time-to-idle expiration, or per-entry variable expiration. So the split is roughly: choose Quick Cache for low overhead and a small dependency tree, choose Moka when you need expiry policies or the lock-free iterator.

One more line in the table is worth noting. The row about background threads reads "Does not use background threads" for Moka v0.12 with the annotation that this changed in v0.12, meaning earlier Moka versions did use them. If you are reading older material about Moka's runtime behaviour, check which version it describes.

Maintenance, features and licence

The last push to the repository was on 2026-08-09, and the most recent release, v0.12.16, was tagged the same day. Before that, v0.12.15 landed on 2026-03-22 and v0.12.14 on 2026-03-02. The repository is not archived. Release cadence is therefore uneven rather than regular, which is normal for a library this size but worth knowing if you depend on a fix landing quickly.

The Cargo.toml sets rust-version to 1.71.1, so that is the minimum supported Rust version for the current release. Features are opt-in: default is empty, and you enable sync or future depending on which cache you need. There are also logging, quanta and atomic64 features. The manifest notes that atomic64 has no effect in v0.12.10 or newer and will be removed in v0.13.0, and that quanta is not expected to make a noticeable performance difference as of v0.12.10 but may matter once cache metrics are added.

On licensing, the package field reads "(MIT OR Apache-2.0) AND Apache-2.0", and the repository carries both LICENSE-APACHE and LICENSE-MIT files. The README links its license badge to the same section. Because the manifest expression combines an OR with an AND, read the actual licence texts and your own policy rather than assuming the usual dual-licence shape applies unchanged.

Editorial conclusion

Adopt Moka when you need a thread-safe Rust cache with near optimal hit ratio, an async variant, weighted bounding or per-entry expiry, and you can accept a dependency tree larger than Mini Moka's. Do not adopt it for WebAssembly or WASI targets, which the README says are unsupported, or when a non-concurrent or lock-per-shard cache is enough. Before committing, read MIGRATION-GUIDE.md for the v0.12 breaking changes and confirm your toolchain is at least Rust 1.71.1, the rust-version in Cargo.toml.

Frequently asked questions

Official sources

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