NSUserDefaults class provides a programmatic interface for interacting with the defaults system. The defaults system allows an application to customize its behavior to match a user’s preferences. For example, you can allow users to determine what units of measurement your application displays or how often documents are automatically saved. Applications record such preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults since they’re commonly used to determine an application’s default state at startup or the way it acts by default.
- iOS 8.0+
- macOS 10.10+
- tvOS 9.0+
- watchOS 2.0+
At runtime, you use an
NSUserDefaults object to read the defaults that your application uses from a user’s defaults database.
NSUserDefaults caches the information to avoid having to open the user’s defaults database each time you need a default value. The
synchronize() method, which is automatically invoked at periodic intervals, keeps the in-memory cache in sync with a user’s defaults database.
NSUserDefaults class provides convenience methods for accessing common types such as floats, doubles, integers, Booleans, and URLs. A default object must be a property list—that is, an instance of (or for collections, a combination of instances of):
NSDictionary. If you want to store any other type of object, you should typically archive it to create an instance of
NSData. For more details, see Preferences and Settings Programming Guide.
Values returned from
NSUserDefaults are immutable, even if you set a mutable object as the value. For example, if you set a mutable string as the value for
"MyStringDefault", the string you later retrieve using
string(forKey:) will be immutable.
A defaults database is created automatically for each user. The
NSUserDefaults class does not currently support per-host preferences. To do this, you must use the CFPreferences API (see Preferences Utilities). However,
NSUserDefaults correctly reads per-host preferences, so you can safely mix CFPreferences code with
If your application supports managed environments, you can use an
NSUserDefaults object to determine which preferences are managed by an administrator for the benefit of the user. Managed environments correspond to computer labs or classrooms where an administrator or teacher may want to configure the systems in a particular way. In these situations, the teacher can establish a set of default preferences and force those preferences on users. If a preference is managed in this manner, applications should prevent users from editing that preference by disabling any appropriate controls.
You can use key-value observing to register observers for specific keys of interest in order to be notified of all updates to a local defaults database. For more details, see Key-Value Observing Programming Guide.
NSUserDefaults class is thread-safe.
Persistence of NSURL and file reference URLs
NSURL instances to refer to files within a process, it's important to make the distinction between location-based tracking (file: scheme URLs that are basically paths) versus filesystem identity tracking (
file: scheme URLs that are file reference URLs). When persisting an
NSURL, you should take that behavior into consideration. If your application tracks the resource being located by its identity so that it can be found if the user moves the file, then you should explicitly write
NSURL bookmark data or encode a file reference URL.
If you want to track a file by reference but you require explicit control over when resolution occurs, you should take care to write out bookmark data to
NSUserDefaults rather than rely on
set(_:forKey:). This allows you to call
URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: at a time when you know your application will be able to handle the potential I/O or required user interface interactions.
Storing Preferences in iCloud
An app can use the iCloud key-value store to share small amounts of data with other instances of itself on the user’s other computers and iOS devices. For example, a magazine app might store the current issue and page number being read by the user so that other instances of the app can open to the same page when launched.
A sandboxed app cannot access or modify the preferences for any other app. (For example, if you add another app's domain using the
addSuite(named:) method, you do not gain access to that app's preferences.)
Attempting to access or modify another app's preferences does not result in an error, but when you do, macOS actually reads and writes files located within your app's container, rather than the actual preference files for the other application.