MMKV — Efficient Mobile Key-Value Storage Framework by WeChat

Introduction

MMKV is an efficient, small, and easy-to-use mobile key-value storage framework created by the WeChat team at Tencent. It relies on memory-mapped files (mmap) for persistence and Protocol Buffers for serialization, achieving read and write speeds that far exceed SharedPreferences and NSUserDefaults.

What MMKV Does

• Provides persistent key-value storage using memory-mapped files for near-instant writes
• Supports multiple data types including strings, integers, floats, byte arrays, and custom Parcelable/NSCoding objects
• Offers multi-process concurrent read/write on Android via file locking
• Delivers cross-platform support for Android, iOS, macOS, Windows, POSIX, and HarmonyOS
• Enables data encryption with AES-128/CFB for sensitive values

Architecture Overview

MMKV maps a file into virtual memory using mmap, so writes go directly to the kernel page cache without explicit I/O calls. Data is encoded with Protocol Buffers in an append-only log. When the file grows beyond a threshold, MMKV performs a full rewrite to reclaim space. A CRC checksum guards against corruption from unexpected process termination.

Self-Hosting & Configuration

• Add the dependency for your platform (CocoaPods, Gradle, pip, or CMake)
• Initialize MMKV once at app startup with a root directory path
• Optionally set a per-instance encryption key for AES-128 protection
• Enable multi-process mode on Android by passing MMKV.MULTI_PROCESS_MODE
• Tune the page-size or file-growth strategy for workloads with very large values

Key Features

• Blazing speed: benchmarks show 1000x faster than SharedPreferences on Android
• Tiny binary size of roughly 400 KB on mobile platforms
• Thread-safe and multi-process-safe with granular file locks
• Automatic data migration helpers from SharedPreferences and NSUserDefaults
• Mature and battle-tested in WeChat, serving over a billion monthly active users

Comparison with Similar Tools

• SharedPreferences — Android-only, synchronous XML I/O, much slower for frequent writes
• NSUserDefaults — Apple-only, plist-backed, no encryption or multi-process safety
• DataStore (Jetpack) — Google's modern replacement for SharedPreferences, but Android-only and coroutine-based
• Realm — Full object database with queries, heavier footprint than a simple KV store
• LMDB — Also mmap-based, but targets server workloads and lacks mobile-first APIs

FAQ

Q: Does MMKV handle process crashes safely? A: Yes. Because mmap writes go to the OS page cache, data survives app crashes. A CRC check detects partial writes on next load.

Q: Can I use MMKV as a general-purpose database? A: MMKV is designed for flat key-value data. For relational or document data, use a proper database like SQLite.

Q: How large can an MMKV file grow? A: There is no hard limit, but MMKV is optimized for many small values. Files over tens of MB may trigger more frequent full-rewrites.

Q: Is MMKV open source? A: Yes. MMKV is released under the BSD 3-Clause license on GitHub.

Sources

• https://github.com/Tencent/MMKV
• https://github.com/Tencent/MMKV/wiki