Why MMKV Beats NSUserDefaults: High‑Performance Key‑Value Storage for iOS

MMKV is a key‑value component based on mmap memory mapping, using protobuf for serialization, offering high performance and strong stability.

Origin of MMKV

In iOS WeChat operations, occasional special characters caused crashes. The solution involved adding counters before and after critical code to detect abnormal characters. Because many cells are displayed, the counters must not affect scrolling performance, and they need to be persisted permanently. Existing storage options such as NSUserDefaults and SQLite could not meet the strict performance requirements, so a high‑performance, general‑purpose key‑value component based on mmap was created.

Principles of MMKV

Memory Preparation

MMKV uses an mmap‑mapped file to provide a memory block that can be written at any time; the app writes data while iOS handles flushing the memory to the file, avoiding data loss on crashes.

Data Organization

Protobuf is used for serialization because of its speed and compactness. Keys are strings; values can be various primitive types (int, bool, double, etc.). Values are serialized into a unified buffer and then stored in memory as KV objects.

Write Optimization

Standard protobuf does not support incremental updates, requiring full writes each time. MMKV implements incremental updates by appending serialized KV objects to the end of the memory region. When the same key is updated, multiple versions exist, with the newest at the end. On startup, MMKV reads the file and replaces older values with the latest, ensuring data freshness.

Space Growth

Appending indefinitely can cause uncontrolled file growth. MMKV mitigates this by allocating space in units of the memory page size and using append mode until the space is exhausted. When the file end is reached, MMKV performs file compaction and key deduplication; if space is still insufficient, the file size is doubled, repeating until enough space is available.

Data Validity

To handle filesystem and OS instability, MMKV adds CRC checks to identify invalid data. In production iOS WeChat, about 700,000 daily checks fail.

Using MMKV

Quick Start

MMKV provides a global instance that can be used directly:

Different business logic can create separate instances if needed:

Supported Data Types

Supported C primitive types: bool, int32, int64, uint32, uint64, float, double

Supported Objective‑C types: NSString, NSData, NSDate

Performance

A simple benchmark comparing MMKV with NSUserDefaults (10,000 write cycles on iPhone X iOS 11.2.6) shows that MMKV is far faster. NSUserDefaults occasionally incurs a costly synchronize operation, while MMKV maintains stable high performance even during file compaction.

MMKV has been open‑sourced internally at Tencent; it may be released publicly if feedback remains positive.