qlImageSize: a QuickLook plugin that shows image dimensions, and why it died

The first line of the README is the status

The README opens with a single sentence that tells you everything about the state of the project: this project is not maintained anymore, it has been killed by macOS 10.15, see issues for details.

That is the whole story of why a plugin that used to be genuinely useful no longer works. The 10.15 release of macOS changed something in the system that the plugin depended on, and the author did not port it.

The repository metadata says the project is not archived and the last push was on 2026-05-04, so there has been recent activity on the branch, but the release history tells a different story about what users get. The recent releases are 2.6.1 from 2019-03-24, 2.6 from 2019-02-21 and 1.6.1 from 2019-02-19. The last published build is from March 2019, and the last release before that from February 2019, so the versions people could install predate the macOS release that broke the plugin.

So the sensible way to treat this repository is as source material rather than as a dependency. It is two plugins, written in Objective-C, that do a small thing well and that demonstrate the structure of a macOS QuickLook generator and a Spotlight metadata importer.

The licence is stated inconsistently, which is worth flagging if you plan to reuse any of it. The badge in the README says BSD, the licence section at the bottom says the project is released under the MIT licence, and the repository's licence field says MIT, with a pointer to the `LICENSE` file at the root. Read that file.

Two plugins, built and shipped separately

The project is composed of both a QuickLook plugin and a Spotlight plugin, and the README says explicitly that both are independent and can be built separately.

The QuickLook one is qlImageSize, a `.qlgenerator`, and it displays the dimensions, DPI and file size of an image in the title bar. The repository description adds the detail that this happens instead of the filename, which is the actual user-facing change. The title bar of a Finder or Preview window normally shows the file name, and with the plugin installed it shows the pixel dimensions, the dots per inch and the size on disk.

The Spotlight one is mdImageSize, a `.mdimporter`, and it displays information about unsupported images, specifically WebP and BPG, in the Finder's inspector window. So the two plugins solve adjacent problems: the first changes what you see when you preview a file, the second changes what the inspector panel shows you about it.

The QuickLook plugin also does more than the title bar. It can preview and generate Finder thumbnails for natively unsupported image formats, and the two named are bpg, the format from Bellard's site, and WebP from Google's project.

That thumbnail generation is the part with the external dependencies. The repository has a `deps/` directory and the README's Upgrading dependencies section explains how to build libwebp and libbpg from source for the current deployment target, which is where most of the build friction lives.

Installing and uninstalling, and where the plugins live

There are three ways to install, and the README lists them as three choices.

The first is Homebrew Cask:

brew install --cask qlimagesize mdimagesizemdimporter

The second is to download the latest build from the releases page and save it to your `~/Library/QuickLook` and/or `~/Library/Spotlight` folder. The third is to build from sources using Xcode, which the README says means just hitting the build button.

The manual install path is the one to understand, because it explains how macOS loads these plugins. There is no installer, no preference pane and no launch agent. The QuickLook generator is a directory in `~/Library/QuickLook` and the Spotlight importer is a directory in `~/Library/Spotlight`, and the system loads them from there. The `qlgenerator/` and `mdimporter/` directories in the repository are the source for those two, and the `qlImageSize.xcodeproj` builds both.

Uninstalling has the same two options. The Homebrew route is:

brew uninstall --cask qlimagesize mdimagesizemdimporter

The manual route is to launch Terminal.app in `/Applications/Utilities` and paste a removal command:

rm -rf ~/Library/QuickLook/qlImageSize.qlgenerator ~/Library/Spotlight/mdImageSize.mdimporter

That last command is the clearest statement of what these plugins are: two bundles in two directories, removable with one recursive delete. There is no state, no background process and no preference file, which is a genuine advantage over the apps that install themselves into the system.

The minimum requirement is macOS High Sierra, 10.13, and that floor is also baked into the build flags the README uses when compiling the dependencies.

The Pixelmator conflict, and what it says about QuickLook plugins

The Limitations section is short and describes one specific problem, and the fix for it is a sequence of commands that tells you a lot about how QuickLook plugins interact.

If you are a Pixelmator user, its own QuickLook plugin might get in the way when previewing WebP files. The fix is to edit the file at `/Applications/Pixelmator.app/Contents/Library/QuickLook/PixelmatorLook.qlgenerator/Contents/Info.plist` and remove the dictionary entry that handles WebP.

And then there is a catch. After editing the Info.plist, QuickLook for the Pixelmator file format might not work, because of code signing. The remedy is to unsign Pixelmator's QuickLook binary using the `unsign` tool, and the README gives the exact commands: it creates another binary with the extension `unsigned`, renames the original for backup, and then removes the extension from the unsigned binary so it takes the original's place.

Three commands of file renaming to make a preview plugin work. That is the cost of a plugin ecosystem where every application registers its own generator for the formats it supports, and where the system picks between them.

The lesson generalises. Any QuickLook generator you write has to coexist with whatever the user's applications have already registered, and the arbitration is by Info.plist declarations rather than by anything the plugin can control. The conflict here is between two plugins both claiming WebP, and it is resolved by making the other one unable to load at all, which is a heavy-handed way to resolve it and the only one the README offers.

Building libwebp and libbpg for the deployment target

The Upgrading dependencies section covers the two native libraries the plugin links against, and the reason both need instructions is that they have to be rebuilt with a deployment target that matches the system the plugin runs on.

For libwebp, the instruction is to grab the latest release, decompress the archive and run:

./autogen.sh
CFLAGS="-mmacosx-version-min=10.13" ./configure --disable-shared
make

The resulting library ends up in `src/.libs/libwebp.a`. The static build is what a plugin bundle needs, since the plugin is loaded into a host process and cannot rely on a shared library being installed on the user's machine. The `CFLAGS` line is the deployment target, and it matches the High Sierra requirement of the plugins themselves.

For libbpg, the instruction is to grab the latest version, decompress the archive and edit the `Makefile` with three changes. Uncomment the line which reads `CONFIG_APPLE=y`. Comment both lines `USE_X265=y` and `USE_BPGVIEW=y`. And replace a block in the makefile so that the Apple configuration adds the deployment flag:

ifdef CONFIG_APPLE
	LDFLAGS+=-Wl,-dead_strip
	CFLAGS+=-mmacosx-version-min=10.13

The `CONFIG_APPLE` switch is what turns on the Apple build path, and `USE_X265` and `USE_BPGVIEW` are commented out because the x265 encoder and the BPG viewer are not needed for a decoder that only has to produce a preview.

Both dependency builds are the kind of step that makes a project unpleasant to resurrect. Two native libraries, each needing a hand-edited build configuration, before the plugin can be compiled at all.

Where qlImageSize is the wrong choice

The first wrong case is a current macOS. The project says so itself: it was killed by macOS 10.15 and is not maintained. The published build is from 2019, and installing it on a modern system either does nothing or breaks something else, which is exactly what the Pixelmator section describes.

The second is a team that just wants the dimensions of an image. macOS already shows the dimensions in Finder's Get Info panel, and Preview shows them too. The plugin's value was putting them in the title bar of the preview window, which is a small convenience, and a small convenience does not justify a plugin that conflicts with another application.

The third is a deployment that cannot have a plugin that reaches into another application's bundle. The Pixelmator workaround edits an Info.plist inside an application and re-signs its binary by hand, and a fleet of managed Macs where the IT team owns the applications is exactly the environment where that is not available.

The fourth is a project that needs WebP or BPG preview in a supported way. Native WebP support has been added to macOS itself, so part of the plugin's reason to exist has gone away, and the format support question for the rest is a general one rather than something this plugin should be relied on for.

What the repository is still good for is as a reference. It is a small, readable Objective-C implementation of a QuickLook generator and a Spotlight metadata importer, split into the two directories the system loads, with the Info.plist and bundle structure you would otherwise have to work out yourself, and it shows the two things a plugin has to get right, which is the title bar text and the thumbnail generation.

Editorial conclusion

qlImageSize is worth reading if you are writing a QuickLook generator or a Spotlight metadata importer for macOS, because the source is small, in Objective-C, and split into the two plugins the system actually loads separately. It is not worth installing on a current macOS, since the README states plainly that the project was killed by macOS 10.15 and is not maintained. Before using any of it, read the first line of the README and check the macOS version in the plugin's Info.plist against the system you are targeting, and note that the licence is stated inconsistently, as BSD in the badge and MIT in the text.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Nyx0uf/qlImageSize on GitHub
4. README
5. Releases