Locating macOS app support, preferences folders

From Lazarus wiki

This article applies to macOS only.

See also: Multiplatform Programming Guide


Before we go any further, let's recap where the Apple Guidelines indicate your application should store its files:

  • Use the Application Support directory (this is backed up by Time Machine), appending your <bundle_ID>, for:
    • Resource and data files that your application creates and manages for the user. You might use this directory to store application state information, computed or downloaded data, or even user created data that you manage on behalf of the user.
    • Autosave files.
  • Use the Caches directory (this is not backed up by Time Machine), appending your <bundle_ID>, for cached data files or any files that your application can recreate easily.
  • Use CFPreferences to read and write your application's preferences. This will automatically write preferences to the appropriate location and read them from the appropriate location. This data is backed up by Time Machine.
  • Use the application Resources directory (this is backed up by Time Machine) for your application-supplied image files, sound files, icon files and other unchanging data files necessary for your application's operation.
  • Use NSTemporaryDirectory (this is not backed up by Time Machine) to store temporary files that you intend to use immediately for some ongoing operation but then plan to discard later. Delete temporary files as soon as you are done with them.

Application Support and Preferences Folders

The function below will return the location the macOS user/global application support directories and the user/global application preferences directories. You would not normally need to manually locate the macOS user preferences directory because the CFPreferences read/write methods will do this for you automatically.

As a bonus, the function below will also return the user/global application support directories for other operating systems.


Note: While the FSFindFolder() function was deprecated by Apple after macOS 10.8 (Mountain Lion), it is still available in macOS 10.15 (Catalina), In the interests of longevity, you my prefer to use the NSSearchPathForDirectoriesInDomains() function instead which is available in macOS 10.0+. See Locating macOS significant directories for details.


  MacOSAll, Files


  {platform-independent method to retrieve application support/preferences directories
   Global: true (global location) _or_ false (user location)
   FolderType: kApplicationSupportFolderType _or_ kPreferencesFolderType
   User preferences live in the location returned by FSFindFolder(kUserDomain,kPreferencesFolderType).
   User application support items live in the location returned by FSFindFolder(kUserDomain, kApplicationSupportFolderType).
   Global preferences live in the location returned by FSFindFolder(kLocalDomain,kPreferencesFolderType).
   Global application support items live in the location returned by FSFindFolder(kLocalDomain, kApplicationSupportFolderType).

function GetSupportDir(Global:boolean; FolderType:LongWord): String;

  kMaxPath = 1024;
  theError: OSErr;
  theRef: FSRef;
  pathBuffer: PChar;
    theRef := Default(FSRef);   // init 

      pathBuffer := Allocmem(kMaxPath);
    except on exception 
      do exit;

      Fillchar(pathBuffer^, kMaxPath, #0);
      Fillchar(theRef, Sizeof(theRef), #0);
      if Global then   // kLocalDomain
        theError := FSFindFolder(kLocalDomain, FolderType, kDontCreateFolder, theRef)
      else             // kUserDomain
        theError := FSFindFolder(kUserDomain , FolderType, kDontCreateFolder, theRef);
      if (pathBuffer <> nil) and (theError = noErr) then
          theError := FSRefMakePath(theRef, pathBuffer, kMaxPath);
          if theError = noErr then 
            GetSupportDir := UTF8ToAnsi(StrPas(pathBuffer)) + '/' + ApplicationName + '/';
    // Other operating systems
    GetSupportDir := GetAppConfigDirUTF8(Global);

Actual preference folder locations

  • Preferences for sandboxed applications with the App Groups entitlement may be found in ~/Library/Group Containers/[app identifier]/Library/Preferences, where [app identifier] is something like com.companyname.appname or org.developername.appname but may be prefaced by alphanumeric characters.
  • Preferences for other sandboxed and all non-sandboxed applications may be found in ~/Library/Containers/[app identifier]/Data/Library/Preferences, where [app identifier] is something like com.companyname.appname or org.developername.appname.
  • Preferences which apply to all users, particularly if they apply before a user logs in, may normally be found in /Library/Preferences.
  • Preferences which apply to an individual user, only after they have logged in, may normally be found in ~/Library/Preferences.

Preference files should be property list files and named something like com.companyname.appname.plist or org.developername.appname.plist. Using the CFPreferences read/write methods will do this for you automatically and will also use the correct folder locations.

See also