Quick Look from the Command Line

Quick Look is macOS’s built-in file preview feature, and you can trigger it directly from the command line using the qlmanage tool. Running qlmanage -p filename opens the Quick Look preview window for that file, while qlmanage -t -s 800 -o . filename generates a thumbnail image instead. This article explains how to use these commands, what options are available, and how to troubleshoot common issues.

What Is Quick Look?

Quick Look was introduced in Mac OS X 10.5 Leopard (2007) as a way to preview files without opening their parent applications. You trigger it in Finder by selecting a file and pressing the Space bar. The preview renders a thumbnail or a full-size view of documents, images, videos, and many other formats. Under the hood, Quick Look uses a system of plugins (called generators) that are installed per file type. Each generator knows how to render a specific format, such as PDF, plain text, or MP4 video.

From the command line, qlmanage is the tool that interfaces with these generators. It lets you do everything the Finder preview does, plus a few extra tricks like generating thumbnails at custom sizes or with transparent backgrounds. This is useful for scripting, batch processing, or simply when you are already in a terminal and want a quick look at a file without leaving it.

Basic Usage: Preview a File

The most common command is qlmanage -p followed by one or more file paths. For example:

qlmanage -p ~/Documents/report.pdf
qlmanage -p photo.jpg video.mov

The -p flag stands for “preview” and opens the Quick Look window, just like pressing Space in Finder. If you pass multiple files, the preview window shows them one at a time with arrow buttons to navigate. The window stays open until you close it, and the command does not return until you do. This is important if you are scripting: the command will block until the user closes the window.

You can also preview a directory. Quick Look will show a generic folder icon, but if you pass a folder path it will still open the preview window. This is rarely useful, but it works.

Generating Thumbnails

If you want a thumbnail image instead of a live preview, use the -t flag. This generates a PNG file (by default) that you can save to a directory with the -o option. For instance:

qlmanage -t -s 512 -o /tmp thumbnails photo.jpg

This creates a 512×512 pixel thumbnail of photo.jpg and saves it to /tmp/thumbnails. The output filename is the original filename with a .png extension (e.g., photo.jpg.png). You can change the size with -s (in pixels). The default size is 1024×1024, but you can set any positive integer. For example, -s 256 gives a small icon.

If you want the thumbnail to have a transparent background (for images with alpha channels), use the -t flag combined with -f (force the generator to use its “full” rendering) and -c to specify a UTI (Uniform Type Identifier) if needed. However, the simplest way to get a transparent background is to use the -t flag with -s and then check the output. Not all generators support transparency; for example, PDFs will always have a white background.

Other Useful Options

The qlmanage tool has several other flags that are handy for scripting and debugging:

• -h – Print help and exit.
• -v – Verbose mode; prints more information about what it is doing.
• -r – Force the generator to re-render, ignoring the cache.
• -c <UTI> – Specify the content type (UTI) to use for the preview. For example, -c public.html forces the HTML generator.
• -d – Display the preview in a window (same as -p but with different internal handling).
• -z – Zoom factor for the preview window (e.g., -z 2 for 200%).
• -p – Preview in a window (as described above).

You can combine flags, but note that -p and -t are mutually exclusive: you either open a window or generate a thumbnail. If you pass both, the last one wins.

Common Problems and Solutions

If you run qlmanage and nothing happens, or you get an error, here are the most likely causes:

• File does not exist – Check the path. The command will silently fail or print an error if the file is not found.
• No generator for the file type – Quick Look may not have a generator for that specific format. In that case, you will see a generic icon or an error message like “Quick Look cannot preview this file.”
• Sandboxing or permissions – If you are running the command from a sandboxed environment (e.g., a terminal that is itself sandboxed), Quick Look may not have access to the file. Try running from the default Terminal app.
• Cache issues – Sometimes Quick Look caches a broken preview. Use qlmanage -r to force a re-render.

If you are trying to generate thumbnails for many files, you might want to loop over them in a shell script. For example, to generate thumbnails for all JPEGs in the current directory:

for file in *.jpg; do
  qlmanage -t -s 256 -o ./thumbs "$file"
done

This will create a thumbs directory (make sure it exists first) with 256×256 PNG thumbnails.

Comparison with Other Tools

On macOS, there are a few other command-line tools that can preview files:

• sips – Primarily for image manipulation, but can also generate thumbnails and convert formats. It works only with image files, not PDFs or videos.
• mdls – Lists metadata attributes for files, but does not render previews.
• textutil – Converts text documents between formats, but does not preview.
• qlmanage is the only one that uses the full Quick Look engine, so it supports the widest range of file types, including videos, Keynote presentations, and 3D models.

If you need to preview files on Linux or Windows, you would use different tools (e.g., evince for PDFs, feh for images). Quick Look is macOS-specific.

Frequently Asked Questions

Can I use Quick Look from the command line on macOS?

Yes, the qlmanage command is built into macOS and does not require any installation. It is located in /usr/bin/qlmanage.

How do I make Quick Look thumbnails with transparent backgrounds?

Use the -t flag and then check the output. Some generators (like those for PNG images) will produce a transparent background if the original image has transparency. For images without alpha, the background will be white. There is no universal flag to force transparency; it depends on the generator.

Why does qlmanage -p not return until I close the window?

Because the preview window is modal. The command waits for the user to close the window before exiting. If you need to run it in the background, add & at the end of the command or use qlmanage -p file &.

Can I preview a file without opening the Quick Look window?

Yes, use the -t flag to generate a thumbnail image instead. That writes a PNG file to disk without opening any window.

How do I specify the output format for thumbnails?

Thumbnails are always saved as PNG, regardless of the input format. There is no option to change the output format; you would need to convert the PNG afterward with sips or another tool.

What if Quick Look cannot preview a file?

Install a Quick Look generator for that file type. Many third-party generators exist, but you need to download them from the developer’s website (e.g., for Adobe Photoshop files). After installing, restart Finder or run qlmanage -r to refresh the cache.

Related

• GIMP Tools vs Photoshop: Which Should You Use?
• Hyundai Santa Fe Hybrid: Perfect Affordable Family SUV?
• Samsung Frame TV Alternatives: Don’t Buy Before Reading