If you encounter problems with QuickLook not creating Thumbnails or Previews properly, one of the first steps is to discover which code is responsible for generating those for QuickLook. Prior to macOS Sequoia, the standard way to do that was using the command tool qlmanage, among whose options is -m, to list all the qlgenerators available on your Mac. If you’ve tried that in Sequoia, you’ll surely have noticed that no longer works.

qlmanage

Since Catalina, Apple has been encouraging developers to switch away from qlgenerators to app extensions to create custom Thumbnails and Previews for QuickLook, and Sequoia is the first version of macOS that can’t use third-party qlgenerators. I have noticed some document types that only a few weeks ago in Sonoma still used custom thumbnails and full previews, but now can’t do so, although others continue to work normally.

These are controlled in the Quick Look item in Login Items & Extensions in General settings.

That should list all third-party app extensions providing this service, and enabling the right one(s) could fix some of those problems. But it turns out this list isn’t complete, and doesn’t in any case tell you which app extension handles which file type. For those, you’d normally turn to qlmanage, but its -m option can only see the qlgenerators in macOS, and no third-party app extensions at all. In fact, qlmanage is now of little help for anything related to QuickLook. I’ve gone back through Sonoma and Ventura, and qlmanage there is no different: although it does list third-party qlgenerators, none of those provided in app extensions appear in its list.

QuickLook app extensions

As far as I can discover, Apple doesn’t provide any equivalent of qlmanage that can report on QuickLook app extensions. The closest it comes is in the pluginkit tool, that can list all app extensions known to macOS. With a bit of tweaking, its -m option can reveal which of those use the QuickLook SDKs for Thumbnails or Previews.

Armed with the appex bundle path from pluginkit, you can then inspect the Info.plist in each, where there’s an array of QLSupportedContentTypes giving the UTIs of all file types supported by that appex. Although I’m sure someone could implement that in a shell script, this seemed an ideal task for my free utility Mints.

Mints and QuickLook

Version 1.20 of my free utility Mints is now available from here: mints120
from Downloads above, from its Product Page, and via its auto-update mechanism.

This adds a twenty-fifth button to the app’s control window, named QuickLook, at the bottom left. Click on that and Mints will open a new window and fill it with information about all the qlgenerators and QuickLook appexes your Mac knows about.

For qlgenerators, you’re given the file UTI, the path to the qlgenerator file, and (when available) its version number, e.g.
com.adobe.pdf /System/Library/QuickLook/PDF.qlgenerator (1002.2.3)

App extensions are divided into two, the first are those providing Previews, and the second those for Thumbnails, e.g.
com.apple.applescript.text /Applications/PreviewCode.app/Contents/PlugIns/Code Previewer.appex

This is an appex provided in one of Black Pyramid Software’s superb Preview series, in PreviewBundle 2 from the App Store (highly recommended).

You will see a few entries like Safari’s
[none] /System/Volumes/Preboot/Cryptexes/App/System/Applications/Safari.app/Contents/PlugIns/SafariQuickLookPreview.appex
with an appex that doesn’t have a list of file types in QLSupportedContentTypes.

Checking UTIs

It’s easy to guess which UTIs represent many file types, but some are a bit more cryptic. For those, copy and paste the UTI into the UTI field of my free UTIutility and it will give you clues as to its identity, including file extensions.

Unfortunately, some of the system qlgenerators support generic UTIs such as
public.audio /System/Library/QuickLook/Audio.qlgenerator (1002.2.3)
public.image /System/Library/QuickLook/Image.qlgenerator (1002.2.3)
public.movie /System/Library/QuickLook/Movie.qlgenerator (1002.2.3)
which clearly cover broad ranges of more specific file types, but don’t provide any more specific information.

How to identify QuickLook extensions

• List installed QuickLook extensions using Mints’ QuickLook button.
• Identify the file’s UTI using UTIutility.
• Locate the UTI in the list of extensions.
• If no match is found, check UTIs listed in UTIutility as Conforms.
• Check Quick Look item in Login Items & Extensions in General settings, to ensure that extension is enabled.

Next up for Mints is a feature to explore app extensions. I may be a little longer on that one.

One of the novel features in the original Finder in Classic Mac OS was the use of distinctive icons for different types of document in an extensible scheme.

Every file had its type and creator codes, each consisting of four single-byte characters. The Desktop databases contained indexes to those, to enable the Finder to display the appropriate icon for a text document of type TEXT created by an app with the creator code of ttxt, SimpleText, for instance.

Apps provided a custom icon in their Resource fork for each type of document they supported. Periodically, those Desktop databases became broken, and documents lost their custom icons. The solution was to rebuild those Desktop databases from the data in each app’s Resources, a procedure that every Mac user became only too familiar with.

At some stage, perhaps in System 6 of 1988, or System 7 of 1991, document icons such as images could be displayed as miniatures or thumbnails instead. This was accomplished by apps creating that file’s thumbnail and saving it as an ICN# resource in the file’s Resource fork. Amazingly, this still works in Sequoia, where I pasted a prepared Resource fork into a Zip file to give it an inappropriate thumbnail.

The raw Resource fork is shown below in xattred as a com.apple.ResourceFork extended attribute.

Initially, Mac OS X continued a similar system, including custom thumbnails, until Apple introduced Quick Look in Mac OS X 10.5 Leopard, in 2007. This came with built-in support for a wide range of common document types, extending to QuickTime media including audio and video. One curious omission at first was that animated GIFs weren’t supported as animations until OS X 10.7.

Display of Thumbnails used the QuickLook framework documented here. This enabled third-parties to extend coverage to their own document types using QuickLook generators with the extension .qlgenerator. Initially, they were installed into /Library/QuickLook from each app bundle.

Normally, when QuickLook generated a Thumbnail or Preview, that was stored in its cache database kept in NSTemporaryDirectory in the path C/com.apple.QuickLook.thumbnailcache/. Those could give revealing insights into images and other documents accessed recently, and Wojciech Regula and Patrick Wardle discovered that, in High Sierra and earlier, it was easy for malicious software to examine that cache. Apple addressed that in macOS 10.14 Mojave by making the cache completely inaccessible.

In-memory caching of Thumbnails has also proved controversial in more recent versions of macOS. To deliver smooth scrolling of Thumbnails in the Finder’s Gallery views in particular, the Finder has taken to caching them in memory for up to two days, sometimes using several GB in the process. That can readily be mistaken for a memory leak, until those cached Thumbnails are finally flushed.

I described how QuickLook Thumbnails worked in early 2019, in the days before the SSV.

When you select a document in the Finder, a dialog, or somewhere else where you expect its icon to be shown, the Finder passes details of the document path and its type (UTI) to IconServices, to fetch the appropriate icon. This calls on its main service, iconservicesd in /System/Library/CoreServices, to check its icon cache.

Although the main icon store is locked away in /Library/Caches/com.apple.iconservices.store, there’s additional data in a folder on a path based on /private/var/folders/…/C/com.apple.iconservices, where … is an unreadable alphanumeric name. For icons used in the Dock, their cache is at /private/var/folders/…/C/com.apple.dock.iconcache. If the icon should be replaced by a QuickLook Thumbnail, such as in a Finder column view, QuickLook is asked to provide that thumbnail. That in turn may be cached in its protected cache at /private/var/folders/…/C/com.apple.QuickLook.thumbnailcache.

QuickLook then relies on there being an appropriate qlgenerator to create a thumbnail of that document type; if the qlgenerator is flawed or can’t cope with the document’s contents, that could easily fall over. For example, if you renamed a text file with a .jpeg extension so that macOS considered it was a JPEG image, the bundled qlgenerator might have simply resulted in the display of a busy spinner, rather than resolving to a generic JPEG document icon. IconServices should then deliver the appropriate icon back to the Finder to display it.

In macOS 10.15 Catalina (2019), Apple started replacing this system with a new framework named QuickLook Thumbnailing, documented here. That replaces qlgenerators with QuickLook preview extensions, in particular Thumbnail Extensions, as explained to developers at WWDC in 2019.

macOS 15.0 Sequoia has finally removed support for qlgenerators. That has resulted in the unfortunate loss of custom Thumbnails and Previews for document types of third-party apps that are still reliant on qlgenerators, and haven’t yet got round to providing equivalent app extensions. It’s almost as if the Desktop databases need to be rebuilt again.

QuickLook is the subsystem in macOS responsible for providing two types of document preview, small Thumbnails and full Previews. If you’ve already upgraded to Sequoia, you’ll have noticed that some document types are no longer displayed with their custom Thumbnails or Previews. This article explains what has happened, and how it should work in the future.

As I’ll detail on Saturday morning, QuickLook (or Quick Look) is the latest in a series of methods for providing custom icons and previews for documents, that started back in the initial versions of Classic Mac OS. macOS ships with its own code to generate Thumbnails and Previews for a wide range of standard file types, from text and PDF to audio and movies. To extend these to other types, developers are encouraged to provide their own code.

Prior to macoS 10.15 Catalina in 2019, the display of Thumbnails was supported by the QuickLook framework. From Catalina onwards, this is provided by a new framework named QuickLook Thumbnailing. The older framework is documented here, and had been deprecated for some years. Its replacement is documented here. To extend these, the older framework used QuickLook generators with the extension .qlgenerator, but in the newer framework this function is provided by QuickLook preview extensions, in particular Thumbnail Extensions, that were explained to developers at WWDC in 2019.

As with most deprecated features, eventually the time comes for Apple to remove support for the old, and for QuickLook generators that has occurred in macOS 15.0 Sequoia. From now on, QuickLook Generator plugins no longer work. Oddly, those provided by macOS in /System/Library/QuickLook are still named with the old extension of .qlgenerator, but all custom support now has to use the new framework in App Extensions.

To check whether an app is still trying to use an old QuickLook Generator, look inside the app bundle in Contents/Library/QuickLook. If you see one or more .qlgenerator bundles there, then those no longer work in Sequoia. Instead, you should see new Thumbnail Extensions in Contents/PlugIns, where you should see App Extension bundles with names ending in something like Thumbnail.appex and QuickLook.appex. Some of the better apps provide both QuickLook Generators for compatibility with Mojave and earlier, and App Extensions for more recent macOS.

If the app you rely on to generate custom QuickLook Thumbnails and Previews doesn’t yet come with those App Extensions, contact their Support and ask them when they’re going to implement the changes brought five years ago in Catalina. Particularly if you’re paying them a subscription, it’s time they caught up. Until they do, I’m afraid those Thumbnails and Previews simply won’t work in Sequoia, and you’ll continue to see generic icons rather than Thumbnails.