Mastering File Previews with ‘qlmanage’ on macOS: A Comprehensive Guide


The Quick Look functionality is a popular feature in macOS that allows users to preview the contents of a file without opening it in its designated application. While commonly accessed through Finder, Quick Look’s capabilities extend to the terminal through the qlmanage command. This guide provides an in-depth understanding of the qlmanage command, its options, and usage examples.

The ‘qlmanage’ Command: Overview

qlmanage is a command-line utility that provides a range of functions associated with Quick Look, including generating thumbnails, previewing files, and testing Quick Look plugins. However, it is crucial to note that qlmanage is considered a debugging tool primarily aimed at developers, and therefore its usage can be a bit more complex than other commands.

Basic Syntax and Common Options

The basic syntax for qlmanage is as follows:

qlmanage [options] file...

The file parameter refers to the file or files you wish to interact with.

Here are some of the most common options associated with qlmanage:

  • -p: Generates a Quick Look preview of the specified files.
  • -t: Generates thumbnail images for the specified files.
  • -o directory: Specifies the directory to store generated files.
  • -s size: Defines the size (in pixels) of the generated thumbnail.

Using ‘qlmanage’

Generating Quick Look Previews

The -p option allows you to generate Quick Look previews of files directly in the terminal. For instance:

qlmanage -p example.txt

This command will open a Quick Look window displaying the contents of example.txt.

Creating Thumbnails

The -t option lets you create a thumbnail image of a file. For example:

qlmanage -t example.jpg

This command generates a thumbnail of example.jpg. The generated thumbnail is saved in the same directory as the original file, with the filename extended with .thumbnail.jpg.

If you want to specify a different output directory for the thumbnail, use the -o option:

qlmanage -t example.jpg -o ~/Desktop/

This command will save the thumbnail to your Desktop.

Adjusting Thumbnail Size

The -s option allows you to specify the size of the generated thumbnail. This size refers to the maximum dimension in pixels (either width or height, depending on the aspect ratio). For instance:

qlmanage -t -s 200 example.jpg

This command will generate a thumbnail for example.jpg, with a maximum dimension of 200 pixels.

Adjusting Thumbnail Size with a Factor

The -f option in qlmanage gives you another way to adjust the size of generated thumbnails. Unlike the -s option, which directly sets the size in pixels, the -f option sets the size as a factor of the original size.

For instance, if you have a large image and want to create a thumbnail that’s half the size of the original, you would use a factor of 0.5. Here’s how you would do it:

qlmanage -t -f 0.5 example.jpg

In this command, -f 0.5 tells qlmanage to create a thumbnail that is 0.5 times (or 50%) the size of example.jpg.

Just like with -s, the -f option works in conjunction with -t for generating thumbnails. You can also use -o to specify a different output directory for the thumbnail.

This factor-based resizing functionality is particularly useful when working with images of varying sizes. It ensures that the thumbnails you generate maintain their relative proportions to the original images, providing consistent previews across different files.


While qlmanage might be primarily intended as a debugging tool for developers, its functionality is beneficial to regular macOS users as well. It allows you to take advantage of Quick Look’s file preview and thumbnail generation capabilities directly from the terminal.

As you integrate qlmanage into your terminal workflow, you’ll discover a flexible and powerful tool that can further streamline your file management and preview tasks on macOS.


Whilst building web applications, Daniel also sets up web servers from scratch because he has yet to find the perfect hosting solution. His philosophy is “Why settle, when you can build it better yourself?”

Recent Posts