Inside QuickLook previews with qlmanage

QuickLook (or Quick Look as it is sometimes known) is one of the features in macOS which generally just gets on with the job, and does a very good job too. Every once in a while, though, thumbnails and previews can get a bit muddled. The simple answer is to restart, but even then QuickLook may remain in a bit of a twist.

Thankfully, Apple has provided a handy command tool, qlmanage, primarily intended for developers to unravel problems with their products, but which has some valuable features for users too. As is so often the case, browsing qlmanage‘s man page only tells you a small fraction of its available options and functions; to get full information, use
qlmanage -h


If you want 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
which scales it by a factor of 8. Those may well generate some Permission denied errors, but those can be safely ignored.

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.

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 which claim 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 actually appear, but you’ll be told how long it took to generate. Supply a file list (see below), and its average figure may prove useful.

There are two commands which you can use to reset the QuickLook server’s information, which may be your solution of last resort:
qlmanage -r
which resets the quicklookd server, and forces it to rebuild the list of generator plugins, and
qlmanage -r cache
which 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.

In case you didn’t know, there’s an easy way of adding the full path and name of a folder or file from a Finder window: type the initial part of the command, then drag and drop the folder or file from a Finder window onto the end of the command. Terminal will then add the full path and item name to the end of that command.

Unfortunately, this isn’t smart enough to know when an abbreviated path can be given, and always adds the full path. However, it works a treat with multiple items, when a command supports such a list of files as arguments.

Terminal also has good support for drag and drop of selected text: if you list the contents of the current folder using ls, for example, you can select items within that listing and drag and drop them onto your command line. That doesn’t add their full path, though, so is of more limited value working with files outside your current directory.