Local Storage with shared_preferences in Flutter: The 2026 API Landscape
Choose between SharedPreferencesAsync and SharedPreferencesWithCache in shared_preferences 2.5.6, read and write typed values, migrate off the legacy API, and know when to reach for something else.
Published on • November 2, 2026
AI Assistant

Flags, themes, and first-run state belong in lightweight key-value storage, and shared_preferences (2.5.6, a Flutter Favorite on pub.dev) covers all six Flutter platforms (docs.flutter.dev). Since 2.3.0 it ships three APIs, and the original SharedPreferences is slated for deprecation.
Choosing the Right API
SharedPreferences(legacy) — synchronous getters behind a cache, keys auto-prefixed withflutter., scheduled for deprecation; migrate it away.SharedPreferencesWithCache— one asynccreate(), then synchronous reads; best when hot-path code reads the same few keys constantly.SharedPreferencesAsync— no cache at all, every call reaches the platform: always async, always fresh; the default choice for new code.
All three store only int, double, bool, String, and List<String>.
SharedPreferencesAsync: Always Fresh
Every operation returns a Future, so a stale read is impossible — even across isolates or background engine instances:
final prefs = SharedPreferencesAsync();
await prefs.setBool('repeat', true);
await prefs.setString('theme', 'dark');
await prefs.setStringList('tags', ['flutter', 'state']);
final theme = await prefs.getString('theme'); // null if unset
await prefs.remove('repeat');
await prefs.clear(allowList: {'theme', 'tags'}); // scoped clear
On Android this uses DataStore Preferences by default, the platform-recommended store. To read keys that native code wrote into legacy Android SharedPreferences, pass SharedPreferencesAsyncAndroidOptions with SharedPreferencesAndroidBackendLibrary.SharedPreferences.
SharedPreferencesWithCache: Sync Reads
After the async setup, getters are synchronous — handy inside build():
final prefs = await SharedPreferencesWithCache.create(
cacheOptions: const SharedPreferencesWithCacheOptions(
allowList: {'theme', 'tags'},
),
);
await prefs.setString('theme', 'dark');
final theme = prefs.getString('theme'); // no await
The cache goes stale when another isolate, another engine instance (say firebase_messaging’s background context), or raw native code writes the same store — call prefs.reload() before trusting a read. If most reads need a reload, use SharedPreferencesAsync instead.
Where the Bytes Land
Android → DataStore/SharedPreferences, iOS/macOS → NSUserDefaults, Linux → $XDG_DATA_HOME, Windows → roaming AppData, Web → LocalStorage. Support starts at Android SDK 24 and iOS 13; Windows, macOS, Linux, and web are all covered.
Migrating Off the Legacy API
The helper copies legacy values into the async store; it is safe to run on every launch as long as migrationCompletedKey is never changed or deleted:
import 'package:shared_preferences/util/legacy_to_async_migration_util.dart';
await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary(
legacySharedPreferencesInstance: await SharedPreferences.getInstance(),
sharedPreferencesAsyncOptions: const SharedPreferencesOptions(),
migrationCompletedKey: 'migrationCompleted',
);
When Not to Use It
Writes are asynchronous and nothing guarantees they hit disk before the call returns, so never store secrets or critical data here — reach for flutter_secure_storage with tokens and keys, and Hive, Drift, or sqflite for structured, queryable records.
Pick the API by how fresh your reads must be: SharedPreferencesAsync by default, SharedPreferencesWithCache for hot synchronous reads — and never for anything that must not be lost.