DataStore

Store data asynchronously, consistently, and transactionally, overcoming some of the drawbacks of SharedPreferences
Latest Update Stable Release Release Candidate Beta Release Alpha Release
May 1, 2024 1.1.1 - - -

Declaring dependencies

To add a dependency on DataStore, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

There are two implementations of DataStore: Preferences and Proto. Choose one or the other. You can also add Android-free dependencies to either implementation.

Add the dependencies for the implementation you need in the build.gradle file for your app or module:

Preferences DataStore

Groovy

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.1.1"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.1.1"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.1.1"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.1.1"
    }

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.1.1")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.1.1")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.1.1")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.1.1")
    }

Proto DataStore

Groovy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.1.1"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.1.1"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.1.1"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.1.1"
    }

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.1.1")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.1.1")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.1.1")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.1.1")
    }

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.1

Version 1.1.1

May 1, 2024

androidx.datastore:datastore-*:1.1.1 is released. Version 1.1.1 contains these commits.

Bug Fixes

  • Mitigated Linux false alarm on "Resource deadlock would occur" error in a corner case multiple DataStore instances attempt to write from different processes by backing off the file lock.

Version 1.1.0

April 17, 2024

androidx.datastore:datastore-*:1.1.0 is released. Version 1.1.0 contains these commits.

Major changes since 1.0.0 release

Please review the release notes from alpha and beta versions of 1.1.0 for more info. Some of the major updates in 1.1.0 are:

  • DataStore now supports multiple processes accessing the same file, with support for observability across processes.
  • The new Storage interface allows you to customize how to store or serialize your data models.
  • You can now use DataStore in Kotlin Multiplatform projects.

Version 1.1.0-rc01

April 3, 2024

androidx.datastore:datastore-*:1.1.0-rc01 is released. Version 1.1.0-rc01 contains these commits.

Bug Fixes

  • Fixed the performance degradation where updateData calls didn’t optimize on disk writes if the new data is the same as the old data (d64cfb5)
  • Fixed a race condition where MultiProcess DataStore might miss invalidations during initialization. ((b/326141553),(094c2dd))

Version 1.1.0-beta02

March 6, 2024

androidx.datastore:datastore-*:1.1.0-beta02 is released. Version 1.1.0-beta02 contains these commits.

Bug Fixes

  • Performance improvement on DataStore only collects update notifications when it is observed. (b/267792241)
    • Note that this change might trigger UncompletedCoroutinesError in your tests if you are using the Coroutines testing library. Make sure you pass the TestScope.backgroundScope when initializing DataStore in your tests to avoid this issue.
  • ​Fixed the issue of nested updateData calls on the same instance would deadlock. (b/241760537)
  • Made DataStore no longer throw IOExceptions if it fails to delete SharedPreferences during migration. (b/195553816)
  • Fixed the issue where file rename fails during updateData in non-Android JVM environments. (b/203087070)
  • Fixed the issue where CorruptionException is not handled after DataStore initialization. (b/289582516)

Version 1.1.0-beta01

January 10, 2024

androidx.datastore:datastore-*:1.1.0-beta01 is released with no changes since 1.1.0-alpha07. Version 1.1.0-beta01 contains these commits.

Version 1.1.0-alpha07

November 29, 2023

androidx.datastore:datastore-*:1.1.0-alpha07 is released. Version 1.1.0-alpha07 contains these commits.

API Changes

  • MultiProcessDataStoreFactory methods are no longer experimental.The @ExperimentalMultiProcessDataStore annotation has been removed entirely. (Ieee54, I8e607)

Bug Fixes

  • Rollout the removal of @ExperimentalMultiProcessDataStore annotations to 1.1.0-alpha07. (I8e607)

Version 1.1.0-alpha06

November 1, 2023

androidx.datastore:datastore-*:1.1.0-alpha06 is released. Version 1.1.0-alpha06 contains these commits.

API Changes

  • createSingleProcessCoordinator factory method now receives a file path (String, java.io.File and okio.Path) to be consistent with createMultiProcessCoordinator. (I211c8, b/305755935)

Version 1.1.0-alpha05

September 6, 2023

androidx.datastore:datastore-*:1.1.0-alpha05 is released. Version 1.1.0-alpha05 contains these commits.

API Changes

  • Datastore FileStorage is publicly available now, so clients can provide custom params. (Icb985)
  • Changed OkioStorage constructor to accept an InterProcessCoordinator so that it can be used on Android with MultiProcessCoordinator. (Iecea3)

Bug Fixes

  • Fix MultiProcessCoordinator unable to monitor multiple files in the same directory.
  • Fix unable to detect duplicate files if file paths are not normalized.
  • Fix wrong values returned from RxDataStore#isDisposed.
  • Fix missing proguard configuration for datstore-preferences-core artifact.

Version 1.1.0-alpha04

April 5, 2023

androidx.datastore:datastore-*:1.1.0-alpha04 is released. Version 1.1.0-alpha04 contains these commits.

Bug Fixes

  • Improve internal implementation to avoid a race condition where DataStore’s data flow might emit an older value after an update.

Version 1.1.0-alpha03

March 24, 2023

androidx.datastore:datastore-*:1.1.0-alpha03 is released.

Bug Fixes

  • Removed dependency constraints from Maven artifacts to workaround a build problem in Kotlin Native Targets (b/274786186, KT-57531).

Version 1.1.0-alpha02

March 22, 2023

androidx.datastore:datastore-*:1.1.0-alpha02 is released. Version 1.1.0-alpha02 contains these commits.

Note

Note that this version includes an important internal refactor that merges the implementations for single process and multi process DataStore implementations. Please keep an eye on possible unintended behavior changes (e.g. timing of update notifications). You can use the issue tracker component to report such changes.

New Features

  • You can now use DataStore in KMM projects. Note that non-Android targets of DataStore are still experimental but we decided to merge versions to make it easier for developers to try them.
  • Multi process features are moved from androidx.datastore.multiprocess to androidx.datastore.core.
  • Add a new factory method in androidx.datastore.core.MultiProcessDataStoreFactory to create DataStore instances with Storage objects for file operations.
  • Add a new interface InterProcessCoordinator that helps multiple DataStore instances communicate across processes. Note that, Multi-Process implementation of InterProcessCoordinator is only available on Android.

API Changes

  • Add InterProcessCoordinator to StorageConnection in datastore-core interface (I555bb)
  • Change APIs in datastore-core MultiProcessDataStoreFactory to use Storage. (Iac02f)
  • Move public APIs in datastore-multiprocess to datastore-core (I76d7c)
  • Exposed PreferencesSerializer from datastore-preferences-core (I4b788)
  • Adding @JvmDefaultWithCompatibility annotation (I8f206)

Version 1.1.0-alpha01

November 9, 2022

androidx.datastore:datastore-*:1.1.0-alpha01 is released. Version 1.1.0-alpha01 contains these commits.

New Features

  • Support multi-process use cases where data consistency is guaranteed among DataStore instances across processes. Add MultiProcessDataStoreFactory#create to create such DataStore instances.
  • New Storage interface which allows the underlying storage mechanism for Datastore to be switched out. Implementations for java.io and okio are provided. DataStore factories have new methods which accept this Storage object.

API Changes

  • Change APIs in datastore-core MultiProcessDataStoreFactory to use Storage. (Iac02f)
  • Move public APIs in datastore-multiprocess to datastore-core (I76d7c)
  • Exposed PreferencesSerializer from datastore-preferences-core (I4b788)

Version 1.0.0

Version 1.0.0

August 4, 2021

androidx.datastore:datastore-*:1.0.0 is released. Version 1.0.0 contains these commits.

Major features of 1.0.0

Jetpack DataStore is a data storage solution that allows you to store key-value pairs or typed objects with protocol buffers. DataStore uses Kotlin coroutines and Flow to store data asynchronously, consistently, and transactionally.

Version 1.0.0-rc02

July 21, 2021

androidx.datastore:datastore-*:1.0.0-rc02 is released. Version 1.0.0-rc02 contains these commits.

Bug Fixes

  • Clarify that SharedPreferencesMigration does not run if there are no keys. (Icfa32, b/192824325)
  • Fix bug where SharedPreferencesMigration constructed with MIGRATE_ALL_KEYS would throw an exception if the key requested does not yet exist. (Ie318a, b/192824325)

Version 1.0.0-rc01

June 30, 2021

androidx.datastore:datastore-*:1.0.0-rc01 is released. Version 1.0.0-rc01 contains these commits.

Bug Fixes

  • Fixes bug where .java file was inadvertently added into final jar (I65d96, b/188985637)

Version 1.0.0-beta02

June 16, 2021

androidx.datastore:datastore-*:1.0.0-beta02 is released. Version 1.0.0-beta02 contains these commits.

Bug Fixes

Version 1.0.0-beta01

April 21, 2021

androidx.datastore:datastore-*:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

API Changes

  • Remove JVM overloads for kotlin only methods (I2adc7)

Bug Fixes

  • Fixed a bug where datastore delegates could result in leaking contexts (Ie96fc, b/184415662)

Version 1.0.0-alpha08

March 10, 2021

androidx.datastore:datastore-*:1.0.0-alpha08 is released. Version 1.0.0-alpha08 contains these commits.

API Changes

  • You can now add a migration that depends on context to your dataStore and preferencesDataStore property delegate. (I4ef69, b/173726702)
  • Adds helper functions to get the name of the file if you are no longer using datastore delegate or context.createDataStore (I60f9a)
  • Serializer writeTo and readFrom are now suspending. If you have implemented a Serializer, you will need to update your functions to be suspend functions. (I1e58e)
  • Added property delegates for RxDataStore users. (Ied768, b/173726702)

Bug Fixes

Version 1.0.0-alpha07

February 24, 2021

androidx.datastore:datastore-*:1.0.0-alpha07 is released. Version 1.0.0-alpha07 contains these commits.

API Changes

  • The Context.createDataStore extension function has been removed and replaced with globalDataStore property delegate. Call globalDataStore once at the top level in your kotlin file. For example:

    val Context.myDataStore by dataStore(...)

    Put this at the top level of your kotlin file so there is only one instance of it. (I57215, b/173726702)

  • The RxDataStore functions are now on an RxDataStore class instead of extension functions on DataStore. (Idccdb, b/177691248)

  • If you want to migrate EncryptedSharedPreferences (or direct boot SharedPreferences) to DataStore you can now do that with the new SharedPreferencesMigration constructor that allows you to inject the SharedPreferences. (I8e04e, b/177278510)

Bug Fixes

  • DataStore will now throw an exception if there are multiple active DataStores for the same file. If you were not managing your DataStore as a Singleton or were not ensuring that no two instances of DataStore are simultaneously active for a file then you may now see exceptions when reading or writing to DataStore. These can be fixed by managing your DataStore as a Singleton. (Ib43f4, b/177691248)
  • Fix cancellation behavior when caller scope is cancelled. (I2c7b3)

Version 1.0.0-alpha06

January 13, 2021

androidx.datastore:datastore-*:1.0.0-alpha06 is released. Version 1.0.0-alpha06 contains these commits.

New Features

  • Added RxJava wrappers for DataStore. The datastore-rxjava2/3 artifacts contain the wrappers for the core DataStore APIs (RxDataStore, RxDataStoreBuilder, and RxDataMigration). The datastore-preferences-rxjava2/3 artifacts contain a builder to construct a Preferences DataStore.

API Changes

  • Hide the CorruptionHandler interface. There was no reason for it to be public because the DataStore factory only accepts a ReplaceFileCorruptionHandler. (I0b3b3, b/176032264)
  • The preferencesKey<T>(name: String): Key<T> method has been removed and replaced with methods specific to each supported type, for example preferencesKey<Int>("int") is now intPreferencesKey("int") (Ibcfac, b/170311106)

Bug Fixes

  • Fixes documentation on DataStoreFactory which left out the fact that the datastore file is created in the “datastore/” subdirectory. (Ica222)

Version 1.0.0-alpha05

December 2, 2020

androidx.datastore:datastore-*:1.0.0-alpha05 is released. Version 1.0.0-alpha05 contains these commits.

Bug Fixes

  • Add better documentation and exceptions around concurrent writes from datastores. (Ia98a2, b/173522155, b/173726702)
  • We now allow (but don't require) the OutputStream passed to Serializer.writeTo() to be closed. (I5c9bf, b/173037611)

Version 1.0.0-alpha04

November 17, 2020

androidx.datastore:datastore-*:1.0.0-alpha04 is released. Version 1.0.0-alpha04 contains these commits.

Bug Fixes

  • Fixed a packaging issue that causes the following crash in Preference Datastore 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Version 1.0.0-alpha03

November 11, 2020

androidx.datastore:datastore-*:1.0.0-alpha03 is released. Version 1.0.0-alpha03 contains these commits.

New Features

  • Preferences now supports double values (which is useful if you need more precision than floats) (I5be8f, b/169471808)

API Changes

  • Created a pure kotlin dependency for datastore to allow for faster compilation. androidx.datastore:datastore-core contains the core kotlin only APIs and androidx.datastore:datastore contains the APIs that depend on android (including the SharedPreferencesMigration and the Context.createDataStore constructor.)(I42d75, b/168512698)
  • Splitting out targets for preferences data store for faster kotlin compilation (Ia3c19)

  • Serializers now require a new property for the default value that will be used if there is no data on disk. This makes it easier to implement custom serializers so users do not have to special case empty input streams (empty input streams don't parse with json).

    • Also there is now a check to confirm that the output stream provided to writeTo() is not closed, and if it is closed it throws exceptions (I16e29)

  • Making the constructor for SharedPreferencesView internal. It was originally public to allow for testing. Tests should instead construct a SharedPreferencesMigration and test against that. (I93891)

Bug Fixes

  • The produceFile parameter on DataStoreFactory and PreferenceDataStoreFactory is now the last parameter in the list so it lets you use the kotlin trailing lambda syntax. (Ibe7f1, b/169425442)
  • Following the new explicit API requirements for kotlin (I5ae1e)

Known Issues

  • Preference Datastore crashes with java.lang.NoClassDefFoundError. (b/173036843)

Version 1.0.0-alpha02

October 14, 2020

androidx.datastore:datastore-core:1.0.0-alpha02 and androidx.datastore:datastore-preferences:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

Bug Fixes

  • Added a safeguard against mutation in datastore-core. Mutation breaks datastore usage for people using datastore with non-proto/non-preferences types (I6aa84)
  • Added a toString method to Preferences.kt to make current state easy to debug (I96006)
  • Added an exception to safeguard against misuse of DataStore.Preferences (I1134d)
  • Fixed a bug that would cause the app to crash on start up (I69237, b/168580258)

Version 1.0.0-alpha01

September 2, 2020

androidx.datastore:datastore-core:1.0.0-alpha01 and androidx.datastore:datastore-preferences:1.0.0-alpha01 are released. Version 1.0.0-alpha01 contains these commits.

New Features

Jetpack DataStore is a new and improved data storage solution aimed at replacing SharedPreferences. Built on Kotlin coroutines and Flow, DataStore provides two different implementations:

  • Proto DataStore, that lets you store typed objects (backed by protocol buffers)
  • Preferences DataStore, that stores key-value pairs

Data is stored asynchronously, consistently, and transactionally, overcoming most of the drawbacks of SharedPreferences.