A quick look at QuickLook and its problems

QuickLook, or Quick Look, originated in classic Mac OS from thumbnail previews of images that were added by photo editing apps to files as resources (in their resource fork). When available, those replaced icons set by document type for display in the Finder, enabling images to be distinguished readily without having to open them.

QuickLook was introduced in OS X 10.5 Leopard in 2007, and since then has become increasingly capable. It currently provides two types of preview of file contents outside their editing app: thumbnails, smaller previews shown in Finder windows, and previews, presented in their own floating window.

QuickLook works by creating thumbnail and preview files using a type-specific qlgenerator plugin. Many are provided in macOS, where they’re stored in /System/Library/QuickLook on the SSV. Custom qlgenerators can either be added to the /Library/QuickLook folder on the Data volume or, as is now preferred, stored in the app bundle in the path /Contents/Library/QuickLook.

Thumbnail files are cached in one of the warren of folders in /var/folders/ on the Data volume of the current boot volume group. In the past, those caches were readily accessible to intruders, but since macOS High Sierra Apple has progressively locked both the QuickLook database and its cached thumbnails down. From Mojave on, the cache has been sealed in a DataVault, although it may still be possible to access its contents during forensic analysis.

In recent years, QuickLook has expanded its capabilities. Thumbnails now support greater sizing and quality, and as a result the Finder now caches them in memory, resulting in what at first appeared to be a memory leak. That enables rapid scrolling through large thumbnails of images, but in worst cases can result in the Finder retaining several GB of thumbnails in memory for around two days, unless they’re purged because of memory pressure. Previews now support features such as Live Text as well as copying of their contents.

While QuickLook has been relatively free of problems in recent versions of macOS, it can sometimes stumble over some file types and individual files. macOS provides a command line tool, qlmanage, primarily intended for developers debugging their own qlgenerator plugins, and that can be helpful to identify the source of a problem and solve it. It can also be used to view thumbnails and previews from the command line in Terminal.

To see a QuickLook preview of any document from the command line, use the -p option as in
qlmanage -p myPDF.pdf
for the file myPDF.pdf. You can also get a basic thumbnail using the -t option, but will probably want to scale it up using
qlmanage -t -f 8 myPDF.pdf
to scale it by a factor of 8.

If you’re experiencing problems with thumbnails or previews, testing those out using the -p or -t options is a useful first step, and may reveal the cause of the problem, such as a missing or incorrect generator. You can get a good general overview of QuickLook’s health using
qlmanage -m
which returns

general information about the QuickLook server quicklookd
server memory use and the number of used descriptors out of a total of 256 available
a full listing of all known qlgenerator plugins, giving their version numbers in parentheses.

QuickLook selects the qlgenerator to be used for each file according to its type or UTI. qlmanage‘s listing of known qlgenerator plugins gives the UTI for each, followed by their path. For example:

public.plain-text -> /System/Library/QuickLook/Text.qlgenerator (986.5.2) is for plain text files, and naturally uses a macOS plugin
com.microsoft.powerpoint.pot -> /System/Library/QuickLook/Office.qlgenerator (47) uses another macOS plugin to handle Microsoft Powerpoint documents
org.neooffice.draw -> /Applications/NeoOffice.app/Contents/Library/QuickLook/neopeek.qlgenerator (1.1.1) uses a third-party plugin for NeoOffice drawings
dyn.ah62d4um4ge80k2py -> /Library/QuickLook/omalook3.qlgenerator (1.0) is more worrying, as the UTI given is dynamic, so doesn’t refer to a known document type, and this has been installed in the main Library folder by a third party.

If you know which document type is suffering problems, you should be able to locate its plugin, and replace or update it. If you have two or more plugins claiming to handle the same document type, or you think the wrong generator or content type is being used, consider
qlmanage -p -c public.svg-image myDoc
to force the document type to that of an SVG image, for example, or
qlmanage -p -g /System/Library/QuickLook/Office.qlgenerator myDoc
to force the generator to be used to that specified. The full listing of plugins given by the -m option comes in handy here.

If you’re having problems with just one particular document, one trick to try is to generate its thumbnail or preview and obtain performance figures. To do that, the respective commands look like
qlmanage -t -z MyDoc
for a thumbnail, and
qlmanage -p -z MyDoc
for a preview. In both cases, the thumbnail/preview won’t appear, but you’ll be told how long it took to generate. Supply a file list and its average figure could prove useful.

There are two commands you can use to reset the QuickLook server’s information, which could be a solution of last resort:
qlmanage -r
resets the quicklookd server, and forces it to rebuild the list of qlgenerator plugins, and
qlmanage -r cache
resets the thumbnail cache. I don’t think that either of those normally occurs when you start up in Safe mode, so if you do want to reset them, this command is the only accessible method of doing so.

Summary

QuickLook is responsible for thumbnails and previews of files.
It depends on its server quicklookd and qlgenerator plugins installed in QuickLook folders and app bundles.
Correct behaviour requires a file to have a known type, and that type to have the right plugin available to generate thumbnails and previews.
qlmanage can help you identify and fix QuickLook problems.