--- title: UserDefaults framework: foundation role: symbol role_heading: Class path: foundation/userdefaults --- # UserDefaults An interface to the user’s defaults database, which stores system-wide and app-specific settings. ## Declaration ```swift class UserDefaults ``` ## Mentioned in Accessing settings from your code Adding a settings interface to your app Using the file system effectively ## Overview Overview A UserDefaults object provides access to the defaults system, which is a persistent store for app-specific and system-wide settings. You use this system to store nonsensitive information, such as app-specific configuration details. The system also stores configuration details that apply to all apps, such as the current language settings for the device. In your code, you check values from this system and use them to dynamically alter your app’s appearance or behavior. The term defaults refers to the fact that the stored data determines the default startup state and behavior. important: Don’t store personal or sensitive information as settings. The defaults system stores information on disk in an unencrypted format. Store personal or sensitive information in the person’s Keychain instead. To access the defaults system, obtain a UserDefaults object and call its methods to read and write values. The standard object is a shared object you use to read and write your app’s standard settings. You can also create unique UserDefaults objects to manage specific sets of settings. For example, you can create a UserDefaults object that reads and writes settings your app shares with an app extension. Don’t subclass UserDefaults. Each item you store in a defaults object consists of a key-value pair, where each key is a string that you use to locate the item and each value is a data object. The defaults database supports the same value types found in property list files, including types like Int, Float, Double, Bool, String, URL, NSNumber, Date, Array, and Dictionary. To include other types of objects in the defaults database, archive them to a Data object first and store that object instead. Prefer simple types over custom objects whenever possible. With the exception of managed devices in educational institutions, the system stores defaults locally on the current device. When you write values to a UserDefaults object, the object updates its in-memory version of that information right away, and writes the value to disk asynchronously. When someone backs up their device, the system includes any persistent defaults databases in the backup data. Because the data is device-specific, you don’t use the defaults system to share data between devices. To share data between someone’s devices, use the NSUbiquitousKeyValueStore instead. warning: Don’t access the files of the defaults database directly from the file system. Modifying one of the underlying files directly may cause data loss, a delay in changes being available, or an app crash. In macOS, use the defaults command-line utility to safely view or modify the defaults database outside of your app. While your app is running, the defaults system generates notifications to let you know when values change. To observe changes to individual settings, add a Using Key-Value Observing in Swift to your UserDefaults object, using key names to build the path to the setting you want. To observe changes for all settings, register for a UserDefaults.DidChangeMessage or didChangeNotification with your UserDefaults object. The UserDefaults type is thread-safe, and you can use the same object in multiple threads or tasks simultaneously. important: This API has the potential of being misused to access device signals to try to identify the device or user, also known as fingerprinting. Regardless of whether a user gives your app permission to track, fingerprinting is not allowed. When you use this API in your app or third-party SDK (an SDK not provided by Apple), declare your usage and the reason for using the API in your app or third-party SDK’s PrivacyInfo.xcprivacy file. For more information, including the list of valid reasons for using the API, see Describing use of required reason API. Domains and settings search paths To integrate settings from different sources, the defaults system organizes them into domains. An app defines its own custom settings, but the system defines settings that apply to all apps. Similarly, you might choose to override a specific setting temporarily to test one of your app’s features. The defaults system provides domains for each of these cases along with several others. When you request the value of a setting, the UserDefaults object searches its domains in a specific order until it finds the value you want. The following table lists the key domains that the defaults system supports and their search order. Some domains might not be present for all apps. For example, the managed domain is present only on administrator-managed devices. | | | | | | | | | | | | | | | | The system stores data for most persistent domains on the current device, and doesn’t share that data with other devices. To share settings among all of a person’s devices, save them using an NSUbiquitousKeyValueStore object instead. Settings in managed environments If your app supports managed environments, an administrator might configure any managed devices with a default set of settings. For example, in a computer lab or classrom environment, a teacher might set default settings that the lessons require. Apps can’t write to managed domains, so if your app encounters a managed setting, disable or hide any controls that someone might use to change that setting’s value. To determine if a setting is managed, call the objectIsForced(forKey:) or objectIsForced(forKey:inDomain:) method of your UserDefaults object. An app running on a managed device can use NSUbiquitousKeyValueStore to share small amounts of data with the person’s other devices. Use this store for data that your app can safely share with other instances of itself. For example, a textbook app might save the current page number so that the person can continue reading from the same place on any of their devices. For more details about managing devices, see Device Management. Sandbox considerations A sandboxed app cannot access or modify the settings of another app or process, with the following exceptions: An app can modify settings for one of its app extensions. An app can modify settings for an app group to which it belongs. If you use the addSuite(named:) method to add the identifier for an unrelated app, the method doesn’t give you access to the other app’s settings. Instead, the system writes changes to your app’s settings, not to the third-party app’s settings. important: An app that accesses settings in a suite must also have the App Groups Entitlement. ## Topics ### Creating a user defaults object - [standard](foundation/userdefaults/standard.md) - [init()](foundation/userdefaults/init().md) - [init(suiteName:)](foundation/userdefaults/init(suitename:).md) ### Registering default settings - [register(defaults:)](foundation/userdefaults/register(defaults:).md) ### Getting the value of a key - [bool(forKey:)](foundation/userdefaults/bool(forkey:).md) - [integer(forKey:)](foundation/userdefaults/integer(forkey:).md) - [float(forKey:)](foundation/userdefaults/float(forkey:).md) - [double(forKey:)](foundation/userdefaults/double(forkey:).md) - [url(forKey:)](foundation/userdefaults/url(forkey:).md) - [string(forKey:)](foundation/userdefaults/string(forkey:).md) - [stringArray(forKey:)](foundation/userdefaults/stringarray(forkey:).md) - [data(forKey:)](foundation/userdefaults/data(forkey:).md) - [object(forKey:)](foundation/userdefaults/object(forkey:).md) - [array(forKey:)](foundation/userdefaults/array(forkey:).md) - [dictionary(forKey:)](foundation/userdefaults/dictionary(forkey:).md) - [dictionaryRepresentation()](foundation/userdefaults/dictionaryrepresentation().md) ### Setting the value for a key - [set(_:forKey:)](foundation/userdefaults/set(_:forkey:)-3nn5m.md) - [set(_:forKey:)](foundation/userdefaults/set(_:forkey:)-3v852.md) - [set(_:forKey:)](foundation/userdefaults/set(_:forkey:)-1t5ec.md) - [set(_:forKey:)](foundation/userdefaults/set(_:forkey:)-2w22f.md) - [set(_:forKey:)](foundation/userdefaults/set(_:forkey:)-2bqjt.md) - [set(_:forKey:)](foundation/userdefaults/set(_:forkey:)-8ab6d.md) ### Monitoring settings changes and issues - [UserDefaults.DidChangeMessage](foundation/userdefaults/didchangemessage.md) - [didChangeNotification](foundation/userdefaults/didchangenotification.md) - [UserDefaults.SizeLimitExceededMessage](foundation/userdefaults/sizelimitexceededmessage.md) - [sizeLimitExceededNotification](foundation/userdefaults/sizelimitexceedednotification.md) ### Removing settings values - [removeObject(forKey:)](foundation/userdefaults/removeobject(forkey:).md) ### Adding and removing search domains - [addSuite(named:)](foundation/userdefaults/addsuite(named:).md) - [removeSuite(named:)](foundation/userdefaults/removesuite(named:).md) ### Getting the domain names - [argumentDomain](foundation/userdefaults/argumentdomain.md) - [globalDomain](foundation/userdefaults/globaldomain.md) - [registrationDomain](foundation/userdefaults/registrationdomain.md) - [volatileDomainNames](foundation/userdefaults/volatiledomainnames.md) ### Managing domain-specific values - [persistentDomain(forName:)](foundation/userdefaults/persistentdomain(forname:).md) - [setPersistentDomain(_:forName:)](foundation/userdefaults/setpersistentdomain(_:forname:).md) - [volatileDomain(forName:)](foundation/userdefaults/volatiledomain(forname:).md) - [setVolatileDomain(_:forName:)](foundation/userdefaults/setvolatiledomain(_:forname:).md) - [removePersistentDomain(forName:)](foundation/userdefaults/removepersistentdomain(forname:).md) - [removeVolatileDomain(forName:)](foundation/userdefaults/removevolatiledomain(forname:).md) ### Checking for managed keys - [objectIsForced(forKey:)](foundation/userdefaults/objectisforced(forkey:).md) - [objectIsForced(forKey:inDomain:)](foundation/userdefaults/objectisforced(forkey:indomain:).md) ### Deprecated - [init(user:)](foundation/userdefaults/init(user:).md) - [synchronize()](foundation/userdefaults/synchronize().md) - [resetStandardUserDefaults()](foundation/userdefaults/resetstandarduserdefaults().md) - [persistentDomainNames()](foundation/userdefaults/persistentdomainnames().md) - [completedInitialCloudSyncNotification](foundation/userdefaults/completedinitialcloudsyncnotification.md) - [didChangeCloudAccountsNotification](foundation/userdefaults/didchangecloudaccountsnotification.md) - [noCloudAccountNotification](foundation/userdefaults/nocloudaccountnotification.md) - [Language-Dependent Information Constants](foundation/language-dependent-information-constants.md) ## Relationships ### Inherits From - [NSObject](objectivec/nsobject-swift.class.md) ### Conforms To - [CVarArg](swift/cvararg.md) - [CustomDebugStringConvertible](swift/customdebugstringconvertible.md) - [CustomStringConvertible](swift/customstringconvertible.md) - [Equatable](swift/equatable.md) - [Hashable](swift/hashable.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) ## See Also ### App-specific settings - [Accessing settings from your code](foundation/accessing-settings-from-your-code.md)