Platforms
zotLook carries no viewer. It drives the preview the system already has, which is why what you see is exactly what your file manager shows — third-party preview extensions included.
What each system needs
Nothing to install. Quick Look is part of the system, and zotLook drives the same panel the Finder does.
Requires macOS 12 (Monterey) or later.
The plugin ships a small compiled helper for this, qlpreview, as a signed universal binary — it is the only compiled piece in the package.
GNOME Sushi, the preview that Files (Nautilus) opens on Space.
sudo apt install gnome-sushi # Debian, Ubuntu
sudo dnf install sushi # FedoraIt need not be running: zotLook reaches it over D-Bus, and D-Bus starts it on demand. It works outside GNOME as long as the service is installed and a session bus is running.
One habit of the desktop carries over: the moment the preview opens, GNOME hands it the keyboard, exactly as when Files opens it. From then on the window answers its own keys — Space, Escape or q close it — and zotLook’s shortcuts cannot reach the plugin until Zotero is focused again, where the same press that opened a preview still toggles it. That is Sushi behaving as designed, not a binding gone missing.
The arrow keys belong to that design too: Sushi keeps them and reports each press to whatever opened it as selection movement — that is how Files walks its list with the preview open. zotLook answers the same way, switchable in its settings: an arrow inside the preview moves the selection in your item list, and the preview follows the moment the keys come to rest. It follows with the plain preview whatever was showing, since a contact sheet for every row passed through would mean seconds of rendering apiece. Scrolling inside the preview itself stays the wheel’s job — the Page keys join in after a click into the preview window, which is what hands its content the keyboard focus.
KDE has no comparable system-wide preview service — Kiview is a Dolphin extension without an external interface — so nothing is driven there.
QuickLook, the open-source preview that brings the Space key to Explorer. It must be running; zotLook talks to it over the named pipe it listens on.
Both builds work: the Microsoft Store package and the desktop installer answer alike. Older accounts of this integration say the Store build is sandboxed away from the pipe — measured today, it is not.
The preview opens without taking focus away from Zotero, so the keyboard keeps working where you are — and zotLook asks Windows to keep it that way even when the preview was started with the mouse, from the context menu, which is the one case where QuickLook could otherwise take it. The shortcut that opened a preview closes it again, and so does Escape. Click into the preview and QuickLook’s own keys apply instead, until you click back.
What works where
| macOS | Linux | Windows | |
|---|---|---|---|
| Preview attachments | ✓ | ✓ | ✓ |
| Preview notes | ✓ | ✓ | ✓ |
| EPUB rendered by zotLook | ✓ | ✓ | ✓ |
| Contact sheet | ✓ | ✓ | ✓ |
| Clicking a page opens the reader | ✓ | — | ✓ |
| Contact sheet in a Zotero window | ✓ | ✓ | ✓ |
The one gap is Sushi. Its renderer really does follow links, and it cannot load a zotero: URL — so the links are made inert there on purpose, because a click that fails takes the whole preview down with it. The window variant (Ctrl+Alt+Space) gives Linux the clickable sheet. There is more on that in The contact sheet.
Seen side by side
The same three keystrokes on each system, each driving the preview that system already has. What differs is the panel around the page, not what zotLook does.
Space — the attachment
The highlights are Zotero’s own. They live in its database rather than in the file, so what is previewed is an exported copy with them drawn in.
Ctrl+Shift+Space — the contact sheet
Ctrl+Alt+Space — the sheet in a Zotero window
This one is a Zotero window rather than the system’s panel, which is why it looks the same everywhere — and why the page links work on Linux, where they cannot in Sushi.
Which formats appear where
That is the preview program’s business, not zotLook’s. The table describes each one as it comes; every column can be extended.
| Format | macOS | Linux | Windows |
|---|---|---|---|
| ✓ | ✓ | ✓ | |
| Images (JPEG, PNG, GIF, TIFF, WebP) | ✓ | ✓ | ✓ |
| Camera RAW | ✓ | partly¹ | ✓ |
| Video (MP4, MOV) | ✓ | ✓ | ✓ |
| Video (MKV, AVI) | — | ✓² | ✓ |
| Audio | ✓ | ✓ | ✓ |
| HTML | ✓ | ✓ | ✓ |
| Text and source code | ✓³ | ✓ | ✓ |
| Markdown | — | ✓ | ✓ |
| Office (DOCX, XLSX, PPTX) | ✓ | ✓⁴ | ✓⁵ |
| Archives (ZIP, RAR, 7z) | — | — | ✓ |
| EPUB | zotLook | zotLook | zotLook |
¹ through the system’s image loaders (glycin, formerly GdkPixbuf) · ² through whichever GStreamer codecs are installed · ³ known extensions only; see QLStephen below · ⁴ through LibreOffice, where it is installed · ⁵ through the OfficeViewer plugin, with no Office installed
EPUB is the exception everywhere: none of the three renders an e-book, so zotLook converts it itself — the one format zotLook does not simply hand over. Everything else your preview program can show, zotLook can show.
Extending the preview
Because zotLook drives the system’s preview, anything you install there works in Zotero straight away. A viewer for a format zotLook has never heard of does not have to be built into zotLook.
Quick Look takes extensions as Quick Look generators. The easiest route is Homebrew:
brew install --cask qlmarkdown # Markdown
brew install --cask qlvideo # MKV, AVI, FLV and other video formats
brew install --cask qlstephen # text files with no known extension
brew install --cask betterzip # archives
brew install --cask syntax-highlight # source code, with highlighting
brew install --cask webpquicklook # WebPsindresorhus/quick-look-plugins keeps a maintained list. It leans towards free software and leaves out several that suit a research library particularly well:
| Extension | Formats | |
|---|---|---|
| Book Preview | EPUB, MOBI, FB2, DJVU, CBR, CBZ — with a table of contents | €7.99 |
| Glance | source code (JSON, Python, YAML …), Jupyter, Markdown, TAR/ZIP | free |
| iPreview | as Glance, plus RAR, 7Z, AsciiDoc, TSV as a table, 3D models | €7.99 |
| DicomPreview | DICOM — X-ray and MRI images | free |
| QuickFits | FITS — astrophotography | free |
| Camera RawX | compressed RAF (Fuji), NEF (Nikon), X3F (Sigma) | €12.99 |
| Apparency | what an application is made of | free |
Both show EPUBs, and both with a table of contents — zotLook’s own conversion carries one. So the choice is one of taste: zotLook sets the book in a book-width Palatino column and keeps the publisher’s stylesheets, Book Preview shows it in its own presentation.
To give Book Preview the right of way, switch the conversion off in Settings and the book goes to Quick Look untouched.
For MOBI, DJVU and the comic formats there is no choice: zotLook cannot convert those and only ever hands them over, so the extension is the only route to a preview at all.
macOS decides which one wins, and not always in your favour: a Markdown editor with a rudimentary extension can take precedence over the careful QLMarkdown.
The remedy is System Settings → General → Login Items & Extensions, the Extensions section, then the i beside Quick Look. On macOS 26 (Tahoe), switch the view from “By App” to “By Category” first. An extension can be disabled there without deleting the app it came with.
It cannot be decided per file type. An all-rounder such as Glance or iPreview can only be switched off entirely — which is why several specialised extensions are easier to steer than one universal one.
Since macOS Catalina the system marks downloaded extensions as quarantined, and Quick Look then silently declines to load them — there is simply still no preview. Clear it once:
xattr -d -r com.apple.quarantine ~/Library/QuickLookThen run qlmanage -r, or log out and back in.
Extensions that arrive as an application produce a different complaint — macOS “could not verify it is free of malware”. Allow it under System Settings → Privacy & Security → Security → Open Anyway. App Store extensions are checked by Apple and spare you both.
Extensions live in ~/Library/QuickLook (yours) or /Library/QuickLook (everyone’s). Newer ones arrive as an app carrying a Quick Look extension, which you enable under System Settings → General → Login Items & Extensions.
Since version 51 Sushi has a plugin interface: a plugin is a JavaScript file deriving from the Renderer class, looked for in
$HOME/.local/share/sushi/plugins-1 # yours
/usr/lib/sushi/plugins-1 # everyone'sBefore version 51 the directory was $HOME/.local/share/sushi/viewers.
There is no stock of ready-made Sushi plugins to download. The interface exists and is described in plugins/Plugins.md — but whoever uses it writes the plugin themselves.
In practice Sushi is therefore extended indirectly, through the system libraries its viewers draw on:
| Install this | and Sushi shows |
|---|---|
GStreamer codecs (gstreamer1.0-plugins-bad, -ugly, -libav) |
more video and audio formats |
image loaders (webp-pixbuf-loader, glycin loaders) |
WebP, AVIF, HEIF |
| LibreOffice | DOCX, XLSX, PPTX |
That is not a workaround but the design: for these formats Sushi carries no code of its own and uses what the system can already do.
QuickLook takes extensions as .qlplugin files, and installing one is the simplest of the three:
- Download the
.qlpluginfrom the plugin’s releases page. - Select it in Explorer and press Space — QuickLook previews it itself and offers Install.
- Restart QuickLook.
The project keeps the list under Available Plugins. Useful for academic work, among others:
| Plugin | Formats |
|---|---|
| OfficeViewer | Word, Excel, PowerPoint — with no Office installed |
| JupyterNotebookViewer | .ipynb |
| SqliteViewer | SQLite databases |
| ShapefileViewer | ESRI shapefiles |
| FitsViewer | astrophotography (FITS) |
| Hdf5Viewer | HDF5 datasets |
| CADImport | .dwg, .dxf, .plt, .cgm |
| ExifTool | metadata for many formats |