How to View Images in the Terminal

There are two different meanings of “show an image in the terminal”:

• Render the real bitmap inline: this requires a terminal emulator with an image protocol, such as iTerm2, Kitty, or WezTerm.
• Render an approximate character preview: tools such as chafa convert the image to characters or colored blocks. This works in more terminals, but it is less sharp.

If you only want to open the image from a command line on macOS, use:

open "chart.png"

iTerm2 imgcat

imgcat /path/to/image.png

# If the script is in the current directory
./imgcat "chart.png"

If imgcat is not installed, install iTerm2 Shell Integration or download the helper script:

curl -L https://iterm2.com/utilities/imgcat -o /usr/local/bin/imgcat
chmod +x /usr/local/bin/imgcat

Kitty icat

kitty +kitten icat /path/to/image.png

WezTerm imgcat

wezterm imgcat /path/to/image.png

Generic preview chafa

brew install chafa
chafa /path/to/image.png

This usually does not mean the image is broken. It is a limitation of how character previews work.

• Terminals display a grid of character cells, not the original image pixels.
• Character cells are often not square, so aspect ratio and details are approximated.
• A 256-color terminal will look much worse than a truecolor terminal.
• The default output size depends on the current terminal window size.

These options can improve the result:

chafa --size=120x60 image.png
chafa --symbols=block --size=120x60 image.png
chafa --colors=full --size=120x60 image.png
chafa --format=symbols --symbols=space --fill=block --colors=full image.png

The biggest improvements usually come from enlarging the terminal window, reducing the font size, and using a truecolor terminal. For high-resolution inline images, use imgcat, kitty +kitten icat, or wezterm imgcat instead.

kitty is not a built-in macOS command. It is a terminal emulator. This error means Kitty is not installed, or its executable is not in your PATH.

Install it on macOS with:

brew install --cask kitty

Then open the Kitty terminal and run:

kitty +kitten icat image.png

If you do not want to switch terminals, use the method for your current terminal: imgcat in iTerm2, wezterm imgcat in WezTerm, or open/chafa in a regular terminal.

If ./imgcat "chart.png" appears to do nothing, the most common cause is that your current terminal does not support iTerm2's image protocol.

Check the terminal first:

echo $TERM_PROGRAM

If the output is not iTerm.app, for example Apple_Terminal, vscode, or WarpTerminal, imgcat may not render an image.

Then verify the script and image file:

ls -l ./imgcat "chart.png"
file "chart.png"

# If imgcat is not executable
chmod +x ./imgcat

You can also check whether the script itself prints help:

./imgcat --help

If help output appears but the image does not render, the terminal image protocol is the likely issue. Open iTerm2, go to the image directory, and run ./imgcat "chart.png" there.

Use case	Command	Notes
Open the image externally	open image.png	Uses the system image viewer instead of rendering inline.
Rough preview in a regular terminal	chafa --colors=full --size=160x80 image.png	Portable, but detail is limited.
Inline display in iTerm2	imgcat image.png	Run it inside iTerm2.
Inline display in Kitty	kitty +kitten icat image.png	Requires Kitty.
Inline display in WezTerm	wezterm imgcat image.png	Requires WezTerm.