(Published: 2026-02-10)

Terminal Image Display with WezTerm

For the longest time I’ve been struggling with image display in terminals. I either never bothered to put in the effort to configure it, or I was in config hell trying to figure out which program or layer was blocking the image display.

Now that I’ve ditched Ghostty and went back to WezTerm (I am so glad I did this, but that deserves its own blog), I finally got a working terminal setup with image display both with and without tmux.

Here’s how I did it, and some notes for reproducibility.

WezTerm built-in command

WezTerm has the wezterm CLI command for interacting with the terminal. This command includes a built-in imgcat subcommand that outputs an image to the terminal. This subcommand also respects tmux passthrough with an option flag.

Custom script

I created the following script for printing image output to the terminal, both within tmux and outside of it:

#!/usr/bin/env sh

# Script name: `img`

if [ -n "$TMUX" ]; then
    wezterm imgcat --tmux-passthru detect --max-pixels 2000000 "$@"
else
    wezterm imgcat "$@"
fi

Note: The max-pixels makes it so that tmux doesn’t have issues displaying large or high resolution image files (this happened a lot.)

Config

This config line is needed for WezTerm to enable the kitty image display protocol and allow for images to be displayed using escape sequences.

-- Required for reliable image rendering
config.enable_kitty_keyboard = true

File manager previews

I wrestled for hours with ranger and lf with no luck because they were all really hacky and error-prone.

Come to find out, yazi works like a charm out of the box because it already speaks the kitty image display protocol. No extra configuration needed, and it works in tmux without even needing to use the img script I showed above.

Cherry on top

Just to make things even smoother with yazi, I added PDF image previews in the terminal which requires poppler to be installed. Very straight forward install with brew.