wezterm imgcat

Display images in the terminal with WezTerm

The imgcat command outputs images to the terminal, allowing you to view image files directly in your WezTerm session.

Synopsis

wezterm imgcat [OPTIONS] [FILE_NAME]

Description

Displays an image file in the terminal using the iTerm2 inline images protocol. WezTerm supports rendering images with automatic sizing, aspect ratio preservation, and various formatting options.

Arguments

FILE_NAME · path

The name of the image file to be displayed.

If omitted, imgcat will attempt to read the image data from stdin, allowing you to pipe images from other commands.

Supported formats: PNG, JPEG, GIF (including animated), BMP, and other formats supported by the image library.

Examples:

wezterm imgcat screenshot.png
curl https://example.com/image.jpg | wezterm imgcat

Display Options

--width · dimension

Specify the display width. Defaults to "auto" which automatically selects an appropriate size.

Format options:

• N - Number of cells (e.g., 80)
• Npx - Number of pixels (e.g., 800px)
• N% - Percentage of terminal width (e.g., 50%)
• auto - Automatic sizing (default)

Examples:

wezterm imgcat --width 40 image.png
wezterm imgcat --width 800px image.png
wezterm imgcat --width 50% image.png

--height · dimension

Specify the display height. Defaults to "auto" which automatically selects an appropriate size.

Format options:

• N - Number of cells (e.g., 24)
• Npx - Number of pixels (e.g., 600px)
• N% - Percentage of terminal height (e.g., 50%)
• auto - Automatic sizing (default)

Example:

wezterm imgcat --height 20 image.png

--no-preserve-aspect-ratio · flag

Do not respect the aspect ratio. The default is to respect the aspect ratio.

When aspect ratio is preserved (default), specifying only width or height will automatically calculate the other dimension. Use this flag to force exact dimensions.

Position and Cursor Options

--position · x,y

Set the cursor position prior to displaying the image.

The default is to use the current cursor position. Coordinates are expressed in cells with 0,0 being the top left cell position.

Format: x,y (comma-separated)

Example:

wezterm imgcat --position 10,5 image.png

--no-move-cursor · flag

Do not move the cursor after displaying the image.

When used from the shell, there is a very high chance that the shell prompt will overwrite the image. You may wish to also use --hold in that case.

--hold · flag

Wait for Enter/Escape/Ctrl-C/Ctrl-D to be pressed after displaying the image.

This is useful when combined with --no-move-cursor to prevent the image from being immediately overwritten by the prompt.

Image Processing Options

--max-pixels · number · default: "25000000"

Set the maximum number of pixels per image frame.

Images will be scaled down so that they do not exceed this size, unless --no-resample is also used. The default value (25,000,000) matches the limit set by WezTerm.

Resampling the image will reduce any animated images to a single frame.

Example:

wezterm imgcat --max-pixels 10000000 large-image.png

--no-resample · flag

Do not resample images whose frames are larger than the --max-pixels value.

This will typically result in the image refusing to display in WezTerm.

--resize · WIDTHxHEIGHT

Pre-process the image to resize it to the specified dimensions, expressed as WIDTHxHEIGHT (e.g., 800x600).

The resize is independent of other parameters that control the image placement and dimensions in the terminal. This is provided as a convenience preprocessing step.

Resizing animated images will reduce the image to a single frame.

Example:

wezterm imgcat --resize 800x600 image.png

--resample-format · enum · default: "input"

Specify the image format to use to encode resampled/resized images.

The default is to match the input format, but you can choose an alternative format.

Possible values:

• png - PNG format
• jpeg - JPEG format
• input - Match input format (default)

Example:

wezterm imgcat --resample-format png image.jpg

--resample-filter · enum · default: "catmull-rom"

Specify the filtering technique used when resizing/resampling images.

The default (catmull-rom) is a reasonable middle ground of speed and quality.

Possible values:

• nearest - Fastest, lowest quality
• triangle - Fast, low quality
• catmull-rom - Balanced (default)
• gaussian - Slower, higher quality
• lanczos3 - Slowest, highest quality

See the image library documentation for examples of the different techniques and their tradeoffs.

Example:

wezterm imgcat --resample-filter lanczos3 image.png

--show-resample-timing · flag

When resampling or resizing, display some diagnostics around the timing/performance of that operation.

Useful for debugging performance issues with large images.

Tmux Integration

--tmux-passthru · enum

How to manage passing the escape sequence through to tmux.

Possible values:

• disable - Don’t use tmux passthrough
• enable - Always use tmux passthrough
• detect - Automatically detect if running in tmux (default)

Example:

wezterm imgcat --tmux-passthru enable image.png

Examples

Basic image display

wezterm imgcat photo.jpg

Display image from URL

curl -s https://example.com/image.png | wezterm imgcat

Display with specific width

wezterm imgcat --width 50% screenshot.png

Display at half terminal size

wezterm imgcat --width 50% --height 50% image.png

Display without preserving aspect ratio

wezterm imgcat --width 80 --height 20 --no-preserve-aspect-ratio logo.png

Display and hold for viewing

wezterm imgcat --hold wallpaper.jpg

Resize large image before display

wezterm imgcat --resize 1920x1080 huge-image.png

High-quality resampling

wezterm imgcat --resample-filter lanczos3 image.png

Display at specific position

wezterm imgcat --position 0,0 banner.png

Display multiple images in a grid

for img in *.png; do
  wezterm imgcat --width 20 --height 10 "$img"
done

Convert and display

convert input.pdf[0] png:- | wezterm imgcat

Screenshot and display

# Linux (with scrot)
scrot -s - | wezterm imgcat

# macOS
screencapture -i -c && pbpaste | wezterm imgcat

Performance Tips

• Large images are automatically resampled to the --max-pixels limit
• Use --resize to preprocess very large images
• For better quality with resampling, use --resample-filter lanczos3
• For faster display of many images, use --resample-filter nearest

Animated GIFs

WezTerm supports animated GIFs:

wezterm imgcat animation.gif

If an animated GIF exceeds the --max-pixels limit and is resampled, it will be reduced to a single frame.

Troubleshooting

Image doesn’t display:

• Check that the image format is supported
• Ensure the image file exists and is readable
• Try with --max-pixels with a smaller value

Image is too large:

• Use --width and --height to control display size
• Use --resize to preprocess the image

Aspect ratio is wrong:

• Check if --no-preserve-aspect-ratio is set
• Specify only width or height and let WezTerm calculate the other

Prompt overwrites image:

• Use --hold to wait before returning to prompt
• Use --no-move-cursor with --hold

Related

• wezterm set-working-directory - Set terminal working directory
• wezterm start - Start a terminal session