# shared_preferences 2.5.6 Flutter plugin for reading and writing simple key-value pairs. Wraps NSUserDefaults on iOS and SharedPreferences on Android. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com flutter pub add 'shared_preferences:2.5.6' ``` Published: 2026-10-05T23:53:39.579508Z Expected archive SHA-256: 1e85e0dccf5b4a016077fea7dfbb4a7cb39c759ac1596fcf60c06deadb7da91f Available in cache; verification: upstream_checksum ## Direct dependencies - flutter: map[sdk:flutter] - shared_preferences_android: ^2.3.4 - shared_preferences_foundation: ^2.5.0 - shared_preferences_linux: ^2.4.0 - shared_preferences_platform_interface: ^2.4.0 - shared_preferences_web: ^2.4.0 - shared_preferences_windows: ^2.4.0 ## Package README (untrusted upstream documentation) # Shared preferences plugin [![pub package](https://img.shields.io/pub/v/shared_preferences.svg)](https://pub.dev/packages/shared_preferences) Wraps platform-specific persistent storage for simple data (NSUserDefaults on iOS and macOS, SharedPreferences on Android, etc.). Data may be persisted to disk asynchronously, and there is no guarantee that writes will be persisted to disk after returning, so this plugin must not be used for storing critical data. Supported data types are `int`, `double`, `bool`, `String` and `List`. | | Android | iOS | Linux | macOS | Web | Windows | |-------------|---------|-------|-------|--------|-----|-------------| | **Support** | SDK 24+ | 13.0+ | Any | 10.15+ | Any | Any | ## Usage ## SharedPreferences vs SharedPreferencesAsync vs SharedPreferencesWithCache Starting with version 2.3.0 there are three available APIs that can be used in this package. [SharedPreferences] is a legacy API that will be deprecated in the future. We highly encourage any new users of the plugin to use the newer [SharedPreferencesAsync] or [SharedPreferencesWithCache] APIs instead. Consider migrating existing code to one of the new APIs. See [below](#migrating-from-sharedpreferences-to-sharedpreferencesasyncwithcache) for more information. ### Cache and async or sync getters [SharedPreferences] and [SharedPreferencesWithCache] both use a local cache to store preferences. This allows for synchronous get calls after the initial setup call fetches the preferences from the platform. However, The cache can present issues as well: - If you are using `shared_preferences` from multiple isolates, since each isolate has its own singleton and cache. - If you are using `shared_preferences` in multiple engine instances (including those created by plugins that create background contexts on mobile devices, such as `firebase_messaging`). - If you are modifying the underlying system preference store through something other than the `shared_preferences` plugin, such as native code. This can be remedied by calling the `reload` method before using a getter as needed. If most get calls need a reload, consider using [SharedPreferencesAsync] instead. [SharedPreferencesAsync] does not utilize a local cache which causes all calls to be asynchronous calls to the host platforms storage solution. This can be less performant, but should always provide the latest data stored on the native platform regardless of what process was used to store it. ### Android platform storage The [SharedPreferencesAsync] and [SharedPreferencesWithCache] APIs can use [DataStore Preferences](https://developer.android.com/topic/libraries/architecture/datastore) or [Android SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) to store data. In most cases you should use the default option of DataStore Preferences, as it is the platform-recommended preferences storage system. However, in some cases you may need to interact with preferences that were written to SharedPreferences by code you don't control. To use the `Android SharedPreferences` backend, use the `SharedPreferencesAsyncAndroidOptions` when using [SharedPreferencesAsync] on Android. ```dart import 'package:shared_preferences_android/shared_preferences_android.dart'; ``` ```dart const SharedPreferencesAsyncAndroidOptions options = SharedPreferencesAsyncAndroidOptions( backend: SharedPreferencesAndroidBackendLibrary.SharedPreferences, originalSharedPreferencesOptions: AndroidSharedPreferencesStoreOptions( fileName: 'the_name_of_a_file', ), ); ``` The [SharedPreferences] API uses the native [Android SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) tool to store data. ## Examples Here are small examples that show you how to use the API. ### SharedPreferences #### Write data ```dart // Obtain shared preferences. final SharedPreferences prefs = await SharedPreferences.getInstance(); // Save an integer value to 'counter' key. await prefs.setInt('counter', 10); // Save an boolean value to 'repeat' key. await prefs.setBool('repeat', true); // Save an double value to 'decimal' key. await prefs.setDouble('decimal', 1.5); // Save an String value to 'action' key. await prefs.setString('action', 'Start'); // Save an list of strings to 'items' key. await prefs.setStringList('items', ['Earth', 'Moon', 'Sun']); ``` #### Read data ```dart // Try reading data from the 'counter' key. If it doesn't exist, returns null. final int? counter = prefs.getInt('counter'); // Try reading data from the 'repeat' key. If it doesn't exist, returns null. final bool? repeat = prefs.getBool('repeat'); // Try reading data from the 'decimal' key. If it doesn't exist, returns null. final double? decimal = prefs.getDouble('decimal'); // Try reading data from the 'action' key. If it doesn't exist, returns null. final String? action = prefs.getString('action'); // Try reading data from the 'items' key. If it doesn't exist, returns null. final List? items = prefs.getStringList('items'); ``` #### Remove an entry ```dart // Remove data for the 'counter' key. await prefs.remove('counter'); ``` ### SharedPreferencesAsync ```dart final asyncPrefs = SharedPreferencesAsync(); await asyncPrefs.setBool('repeat', true); await asyncPrefs.setString('action', 'Start'); final bool? repeat = await asyncPrefs.getBool('repeat'); final String? action = await asyncPrefs.getString('action'); await asyncPrefs.remove('repeat'); // Any time a filter option is included as a method parameter, strongly consider // using it to avoid potentially unwanted side effects. await asyncPrefs.clear(allowList: {'action', 'repeat'}); ``` ### SharedPreferencesWithCache ```dart final SharedPreferencesWithCache prefsWithCache = await SharedPreferencesWithCache.create( cacheOptions: const SharedPreferencesWithCacheOptions( // When an allowlist is included, any keys that aren't included cannot be used. allowList: {'repeat', 'action'}, ), ); await prefsWithCache.setBool('repeat', true); await prefsWithCache.setString('action', 'Start'); final bool? repeat = prefsWithCache.getBool('repeat'); final String? action = prefsWithCache.getString('action'); await prefsWithCache.remove('repeat'); // Since the filter options are set at creation, they aren't needed during clear. await prefsWithCache.clear(); ``` ### Migration and Prefixes #### Migrating from SharedPreferences to SharedPreferencesAsync/WithCache To migrate to the newer `SharedPreferencesAsync` or `SharedPreferencesWithCache` APIs, import the migration utility and provide it with the `SharedPreferences` instance that was being used previously, as well as the options for the desired new API options. This can be run on every launch without data loss as long as the `migrationCompletedKey` is not altered or deleted. ```dart import 'package:shared_preferences/util/legacy_to_async_migration_util.dart'; // ยทยทยท const sharedPreferencesOptions = SharedPreferencesOptions(); final SharedPreferences prefs = await SharedPreferences.getInstance(); await migrateLegacySharedPreferencesToSharedPreferencesAsyncIfNecessary( legacySharedPreferencesInstance: prefs, sharedPreferencesAsyncOptions: sharedPreferencesOptions, migrationCompletedKey: 'migrationCompleted', ); ``` #### Adding, Removing, or changing prefixes on SharedPreferences By default, the `SharedPreferences` class will only read (and write) preferences that begin with the prefix `flutter.`. This is all handled internally by the plugin and does not require manually adding this prefix. Alternatively, `SharedPreferences` can be configured to use any prefix by adding a call to `setPrefix` before any instances of `SharedPreferences` are instantiated. Calling `setPrefix` after an instance of `SharedPreferences` is created will fail. Setting the prefix to an empty string `''` will allow access to all preferences created by any non-flutter versions of the app (for migrating from a native app to flutter). If the prefix is set to a value such as `''` that causes it to read values that were not originally stored by the `SharedPreferences`, initializing `SharedPreferences` may fail if any of the values are of types that are not supported by `SharedPreferences`. In this case, you can set an `allowList` that contains only preferences of supported types. If you decide to remove the prefix entirely, you can still access previously created preferences by manually adding the previous prefix `flutter.` to the beginning of the preference key. If you have been using `SharedPreferences` with the default prefix but wish to change to a new prefix, you will need to transform your current preferences manually to add the new prefix otherwise the old preferences will be inaccessible. ### Storage location by platform | Platform | SharedPreferences | SharedPreferencesAsync/WithCache | | :--- | :--- | :--- | | Android | SharedPreferences | DataStore Preferences or SharedPreferences | | iOS | NSUserDefaults | NSUserDefaults | | Linux | In the XDG_DATA_HOME directory | In the XDG_DATA_HOME directory | | macOS | NSUserDefaults | NSUserDefaults | | Web | LocalStorage | LocalStorage | | Windows | In the roaming AppData directory | In the roaming AppData directory | ## Changelog ## 2.5.6 * Documents the meaning of the return values of the set and remove methods. * Updates minimum supported SDK version to Flutter 3.41/Dart 3.11. ## 2.5.5 * Fixes dartdoc comments that accidentally used HTML. ## 2.5.4 * Updates dependencies for the `shared_preferences_tool` DevTools extension and fixes related deprecations. * Updates minimum supported SDK version to Flutter 3.35/Dart 3.9. * Updates README to reflect currently supported OS versions for the latest versions of the endorsed platform implementations. * Applications built with older versions of Flutter will continue to use compatible versions of the platform implementations. ## 2.5.3 * Fixes a bug in the example app. ## 2.5.2 * Fixes `setState` returning `Future` on `example/main.dart` error in example code. ## 2.5.1 * Exposes `SharedPreferencesOptions`. ## 2.5.0 * Adds shared preferences devtools extension. ## 2.4.0 * Adds migration tool to move from legacy `SharedPreferences` to `SharedPreferencesAsync`. * Adds clarifying comment about `allowList` handling with an updated prefix. ## 2.3.5 * Adds information about Android SharedPreferences support. ## 2.3.4 * Security update, requires shared_preferences_android to be 2.3.4. ## 2.3.3 * Clarifies scope of prefix handling in README. ## 2.3.2 * Removes outdated testing information from README. * Updates minimum supported SDK version to Flutter 3.22/Dart 3.4. ## 2.3.1 * Fixes `getStringList` bug with `List` cast exception. ## 2.3.0 * Adds `SharedPreferencesAsync` and `SharedPreferencesWithCache` APIs. * Updates minimum supported SDK version to Flutter 3.16/Dart 3.2. ## 2.2.3 * Updates minimum supported SDK version to Flutter 3.13/Dart 3.1. * Updates support matrix in README to indicate that iOS 11 is no longer supported. * Clients on versions of Flutter that still support iOS 11 can continue to use this package with iOS 11, but will not receive any further updates to the iOS implementation. * Updates minimum supported SDK version to Flutter 3.10/Dart 3.0. * Updates minimum iOS implementation version to include a privacy manifest. ## 2.2.2 * Updates documentation for `containsKey`. ## 2.2.1 * Adds pub topics to package metadata. * Updates minimum supported SDK version to Flutter 3.7/Dart 2.19. * Fixes the example app to be debuggable on Android. * Deletes deprecated splash screen meta-data element. ## 2.2.0 * Adds `allowList` option to setPrefix. ## 2.1.2 * Fixes singleton initialization race condition introduced during NNBD transition. * Updates minimum supported macOS version to 10.14. * Updates minimum supported SDK version to Flutter 3.3/Dart 2.18. ## 2.1.1 * Updates iOS minimum version in README. ## 2.1.0 * Adds `setPrefix` method. ## 2.0.20 * Adds README discussion of `reload()`. ## 2.0.19 * Updates README to use code excerpts. * Aligns Dart and Flutter SDK constraints. ## 2.0.18 * Updates links for the merge of flutter/plugins into flutter/packages. * Updates minimum Flutter version to 3.0. ## 2.0.17 * Updates code for stricter lint checks. ## 2.0.16 * Switches to the new `shared_preferences_foundation` implementation package for iOS and macOS. * Updates code for `no_leading_underscores_for_local_identifiers` lint. * Updates minimum Flutter version to 2.10. ## 2.0.15 * Minor fixes for new analysis options. ## 2.0.14 * Adds OS version support information to README. * Fixes library_private_types_in_public_api, sort_child_properties_last and use_key_in_widget_constructors lint warnings. ## 2.0.13 * Updates documentation on README.md. ## 2.0.12 * Removes dependency on `meta`. ## 2.0.11 * Corrects example for mocking in readme. ## 2.0.10 * Removes obsolete manual registration of Windows and Linux implementations. ## 2.0.9 * Fixes newly enabled analyzer options. * Updates example app Android compileSdkVersion to 31. * Moved Android and iOS implementations to federated packages. ## 2.0.8 * Update minimum Flutter SDK to 2.5 and iOS deployment target to 9.0. ## 2.0.7 * Add iOS unit test target. * Updated Android lint settings. * Fix string clash with double entries on Android ## 2.0.6 * Migrate maven repository from jcenter to mavenCentral. ## 2.0.5 * Fix missing declaration of windows' default_package ## 2.0.4 * Fix a regression with simultaneous writes on Android. ## 2.0.3 * Android: don't create additional Handler when method channel is called. ## 2.0.2 * Don't create additional thread pools when method channel is called. ## 2.0.1 * Removed deprecated [AsyncTask](https://developer.android.com/reference/android/os/AsyncTask) was deprecated in API level 30 ([#3481](https://github.com/flutter/plugins/pull/3481)) ## 2.0.0 * Migrate to null-safety. **Breaking changes**: * Setters no longer accept null to mean removing values. If you were previously using `set*(key, null)` for removing, use `remove(key)` instead. ## 0.5.13+2 * Fix outdated links across a number of markdown files ([#3276](https://github.com/flutter/plugins/pull/3276)) ## 0.5.13+1 * Update Flutter SDK constraint. ## 0.5.13 * Update integration test examples to use `testWidgets` instead of `test`. ## 0.5.12+4 * Remove unused `test` dependency. ## 0.5.12+3 * Check in windows/ directory for example/ ## 0.5.12+2 * Update android compileSdkVersion to 29. ## 0.5.12+1 * Check in linux/ directory for example/ ## 0.5.12 * Keep handling deprecated Android v1 classes for backward compatibility. ## 0.5.11 * Support Windows by default. ## 0.5.10 * Update package:e2e -> package:integration_test ## 0.5.9 * Update package:e2e reference to use the local version in the flutter/plugins repository. ## 0.5.8 * Support Linux by default. ## 0.5.7+3 * Post-v2 Android embedding cleanup. ## 0.5.7+2 * Update lower bound of dart dependency to 2.1.0. ## 0.5.7+1 * Declare API stability and compatibility with `1.0.0` (more details at: https://github.com/flutter/flutter/wiki/Package-migration-to-1.0.0). ## 0.5.7 * Remove Android dependencies fallback. * Require Flutter SDK 1.12.13+hotfix.5 or greater. * Fix CocoaPods podspec lint warnings. ## 0.5.6+3 * Fix deprecated API usage warning. ## 0.5.6+2 * Make the pedantic dev_dependency explicit. ## 0.5.6+1 * Updated README ## 0.5.6 * Support `web` by default. * Require Flutter SDK 1.12.13+hotfix.4 or greater. ## 0.5.5 * Support macos by default. ## 0.5.4+10 * Adds a `shared_preferences_macos` package. ## 0.5.4+9 * Remove the deprecated `author:` field from pubspec.yaml * Migrate the plugin to the pubspec platforms manifest. * Require Flutter SDK 1.10.0 or greater. ## 0.5.4+8 * Switch `package:shared_preferences` to `package:shared_preferences_platform_interface`. No code changes are necessary in Flutter apps. This is not a breaking change. ## 0.5.4+7 * Restructure the project for Web support. ## 0.5.4+6 * Add missing documentation and a lint to prevent further undocumented APIs. ## 0.5.4+5 * Update and migrate iOS example project by removing flutter_assets, change "English" to "en", remove extraneous xcconfigs and framework outputs, update to Xcode 11 build settings, and remove ARCHS. ## 0.5.4+4 * `setMockInitialValues` needs to handle non-prefixed keys since that's an implementation detail. ## 0.5.4+3 * Android: Suppress casting warnings. ## 0.5.4+2 * Remove AndroidX warnings. ## 0.5.4+1 * Include lifecycle dependency as a compileOnly one on Android to resolve potential version conflicts with other transitive libraries. ## 0.5.4 * Support the v2 Android embedding. * Update to AndroidX. * Migrate to using the new e2e test binding. ## 0.5.3+5 * Define clang module for iOS. ## 0.5.3+4 * Copy `List` instances when reading and writing values to prevent mutations from propagating. ## 0.5.3+3 * `setMockInitialValues` can now be called multiple times and will `reload()` the singleton if necessary. ## 0.5.3+2 * Fix Gradle version. ## 0.5.3+1 * Add missing template type parameter to `invokeMethod` calls. * Bump minimum Flutter version to 1.5.0. * Replace invokeMethod with invokeMapMethod wherever necessary. ## 0.5.3 * Add reload method. ## 0.5.2+2 * Updated Gradle tooling to match Android Studio 3.4. ## 0.5.2+1 * .commit() calls are now run in an async background task on Android. ## 0.5.2 * Add containsKey method. ## 0.5.1+2 * Add a driver test ## 0.5.1+1 * Log a more detailed warning at build time about the previous AndroidX migration. ## 0.5.1 * Use String to save double in Android. ## 0.5.0 * **Breaking change**. Migrate from the deprecated original Android Support Library to AndroidX. This shouldn't result in any functional changes, but it requires any Android apps using this plugin to [also migrate](https://developer.android.com/jetpack/androidx/migrate) if they're using the original support library. ## 0.4.3 * Prevent strings that match special prefixes from being saved. This is a bugfix that prevents apps from accidentally setting special values that would be interpreted incorrectly. ## 0.4.2 * Updated Gradle tooling to match Android Studio 3.1.2. ## 0.4.1 * Added getKeys method. ## 0.4.0 * **Breaking change**. Set SDK constraints to match the Flutter beta release. ## 0.3.3 * Fixed Dart 2 issues. ## 0.3.2 * Added an getter that can retrieve values of any type ## 0.3.1 * Simplified and upgraded Android project template to Android SDK 27. * Updated package description. ## 0.3.0 * **Breaking change**. Upgraded to Gradle 4.1 and Android Studio Gradle plugin 3.0.1. Older Flutter projects need to upgrade their Gradle setup as well in order to use this version of the plugin. Instructions can be found [here](https://github.com/flutter/flutter/wiki/Updating-Flutter-projects-to-Gradle-4.1-and-Android-Studio-Gradle-plugin-3.0.1). ## 0.2.6 * Added FLT prefix to iOS types ## 0.2.5+1 * Aligned author name with rest of repo. ## 0.2.5 * Fixed crashes when setting null values. They now cause the key to be removed. * Added remove() method ## 0.2.4+1 * Fixed typo in changelog ## 0.2.4 * Added setMockInitialValues * Added a test * Updated README ## 0.2.3 * Suppress warning about unchecked operations when compiling for Android ## 0.2.2 * BREAKING CHANGE: setStringSet API changed to setStringList and plugin now supports ordered storage. ## 0.2.1 * Support arbitrary length integers for setInt. ## 0.2.0+1 * Updated README ## 0.2.0 * Upgrade to new plugin registration. (https://groups.google.com/forum/#!topic/flutter-dev/zba1Ynf2OKM) ## 0.1.1 * Upgrade Android SDK Build Tools to 25.0.3. ## 0.1.0 * Initial Open Source release.