Inside Mojave’s Aliases and Bookmarks

In previous articles about Finder Aliases and Bookmarks, I have referred to them as opaque data structures which can be used in the Finder and accessed only in limited ways, for example using Precize to resolve Bookmarks or alisma to access them through the command line. Thanks to the work of Michael Lynn just over three years ago, we can now look inside Bookmarks and Aliases. This article uses a new version of Precize to do exactly that.

To recap: a hard link is just an additional entry in the APFS file system directory which points to the file in storage, and a symbolic link is just a file with a relative path which points to the original file (this relative path may become absolute, e.g. when the original is stored on a different volume).

Apple introduced Finder Aliases in System 7, almost 30 years ago in 1991. Prior to that, users didn’t have access to any form of link or alias, but when the largest hard disk available in a Mac was only 160 MB, that wasn’t such a problem. From the outset, Aliases have been presented as opaque data structures which are handled by the system. Although apps have been able to obtain information from them, Apple hasn’t intended any more general access to the data which they contain.

Bookmarks are a generalisation of Aliases which allow variants, including those saved as files, both the Finder Alias and alisma‘s Bookmarks, which are similar but not identical. Bookmarks have been used extensively internally in macOS and applications since at least Mavericks 10.9 in 2013. They’re now used in a lot of preference files and other places, particularly by Launch Services in its SharedFileList files stored in ~/Library/Application Support/

Prior to macOS Sierra, Finder Aliases (and some Bookmarks) were usually quite large, containing icons and other data, and were typically just over 1 MB on disk. Early releases of Sierra, even 10.12.1, didn’t always work properly with the new compact Bookmark and Alias formats introduced then, but they have since become widespread and generally fully compatible with the system and apps. If you remember struggling with Aliases, it is probably from that time of transition. In Launch Services files, the original Bookmark format was usually contained in .sfl files, and the new in .sfl2 files.

The current Bookmark and Alias format is typically around 1 KB, making them almost as efficient in terms of storage as symbolic links, although macOS continues to use symlinks rather than Aliases in many places, particularly where paths have to be resolved by commands and scripts.

If you want to read a detailed account of the structure and contents of Aliases in El Capitan and HFS+, Michael Lynn’s article remains the reference. Here, I will consider primarily Bookmarks in macOS 10.14 Mojave and APFS.

Among the information stored in Bookmarks is the following:

  • NSURLBookmarkOriginalRelativePathKey – this is the path to the item relative to the root of that volume, e.g. Users/username/Documents/test1.txt
  • NSURLBookmarkOriginalVolumeNameKey – this is the name of that volume, typically Macintosh HD for internal storage
  • NSURLCreationDateKey – this is the date of creation of the item, e.g. 2019-01-07 17:06:59 +0000
  • NSURLDocumentIdentifierKey – an integer which uniquely identifies this item wherever it is on that volume, but this is not the inode number; e.g. 5747
  • NSURLIsDirectoryKey – whether the item is a folder or not
  • NSURLNameKey – the file or folder name, including any extension. e.g. test1.txt
  • NSURLVolumeNameKey – the name of the volume on which the item is stored, which should be the same as that given above; there are also numerous entries giving details about that volume, including its total capacity, whether it’s removable, etc.
  • NSURLVolumeUUIDStringKey – the UUID of the volume on which the item is stored
  • _NSURLBookmarkURLStringKey – the URL to the item, e.g. file:///Users/username/Documents/test1.txt
  • _NSURLFileIDKey – the inode number of the item
  • userName and userUID – the short username of the owner of the item, and their system ID, e.g. 501.

It’s important to note that Bookmarks don’t appear to store the inode number of the volume. Instead, the volume name and UUID are used, which are more stable across reboots and hardware reconfiguration. This explains how Bookmarks and Aliases can preserve links even when both the alias and the original file/folder are moved: macOS first tries to resolve the path, rather like a symlink, and if that fails it has other systems, including inode numbers, which it can fall back on.

The remaining issue with Bookmarks and Aliases is that they cannot ordinarily be resolved at the command line or in scripts. My free tool alisma should be a help, as it can return the absolute path from a Bookmark file or Alias.

This information persists in Bookmarks and Aliases even when they can no longer be resolved, and can therefore be of potential value in forensic and other investigations.

As far as I am aware, access to the whole of this otherwise opaque information hasn’t previously been possible in a GUI application. I have now added this to my free app Precize, so that you can paste Base-64 Bookmarks and Aliases into its Bookmark Resolver window, and the app will generate complete text output of the information within that Bookmark or Alias. Precize will also attempt to resolve that Bookmark or Alias.


Precize version 1.5, which is notarized for Mojave and comes with both a detailed Help book and PDF documentation, is available from here: precize15
and from Downloads above. It runs on all versions of macOS from El Capitan to Mojave.

I am extremely grateful to @mikeymikey for not only writing up his discovery of this method of obtaining detailed information about the contents and structure of bookmarks, but for pointing it out to me.