> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

<ParamField path="FILE_NAME" type="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:**

  ```bash theme={null}
  wezterm imgcat screenshot.png
  curl https://example.com/image.jpg | wezterm imgcat
  ```
</ParamField>

## Display Options

<ParamField path="--width" type="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:**

  ```bash theme={null}
  wezterm imgcat --width 40 image.png
  wezterm imgcat --width 800px image.png
  wezterm imgcat --width 50% image.png
  ```
</ParamField>

<ParamField path="--height" type="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:**

  ```bash theme={null}
  wezterm imgcat --height 20 image.png
  ```
</ParamField>

<ParamField path="--no-preserve-aspect-ratio" type="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.
</ParamField>

## Position and Cursor Options

<ParamField path="--position" type="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:**

  ```bash theme={null}
  wezterm imgcat --position 10,5 image.png
  ```
</ParamField>

<ParamField path="--no-move-cursor" type="flag">
  Do not move the cursor after displaying the image.

  <Warning>
    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.
  </Warning>
</ParamField>

<ParamField path="--hold" type="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.
</ParamField>

## Image Processing Options

<ParamField path="--max-pixels" type="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.

  <Note>
    Resampling the image will reduce any animated images to a single frame.
  </Note>

  **Example:**

  ```bash theme={null}
  wezterm imgcat --max-pixels 10000000 large-image.png
  ```
</ParamField>

<ParamField path="--no-resample" type="flag">
  Do not resample images whose frames are larger than the `--max-pixels` value.

  <Warning>
    This will typically result in the image refusing to display in WezTerm.
  </Warning>
</ParamField>

<ParamField path="--resize" type="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.

  <Note>
    Resizing animated images will reduce the image to a single frame.
  </Note>

  **Example:**

  ```bash theme={null}
  wezterm imgcat --resize 800x600 image.png
  ```
</ParamField>

<ParamField path="--resample-format" type="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:**

  ```bash theme={null}
  wezterm imgcat --resample-format png image.jpg
  ```
</ParamField>

<ParamField path="--resample-filter" type="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](https://docs.rs/image/latest/image/imageops/enum.FilterType.html#examples) for examples of the different techniques and their tradeoffs.

  **Example:**

  ```bash theme={null}
  wezterm imgcat --resample-filter lanczos3 image.png
  ```
</ParamField>

<ParamField path="--show-resample-timing" type="flag">
  When resampling or resizing, display some diagnostics around the timing/performance of that operation.

  Useful for debugging performance issues with large images.
</ParamField>

## Tmux Integration

<ParamField path="--tmux-passthru" type="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:**

  ```bash theme={null}
  wezterm imgcat --tmux-passthru enable image.png
  ```
</ParamField>

## Examples

### Basic image display

```bash theme={null}
wezterm imgcat photo.jpg
```

### Display image from URL

```bash theme={null}
curl -s https://example.com/image.png | wezterm imgcat
```

### Display with specific width

```bash theme={null}
wezterm imgcat --width 50% screenshot.png
```

### Display at half terminal size

```bash theme={null}
wezterm imgcat --width 50% --height 50% image.png
```

### Display without preserving aspect ratio

```bash theme={null}
wezterm imgcat --width 80 --height 20 --no-preserve-aspect-ratio logo.png
```

### Display and hold for viewing

```bash theme={null}
wezterm imgcat --hold wallpaper.jpg
```

### Resize large image before display

```bash theme={null}
wezterm imgcat --resize 1920x1080 huge-image.png
```

### High-quality resampling

```bash theme={null}
wezterm imgcat --resample-filter lanczos3 image.png
```

### Display at specific position

```bash theme={null}
wezterm imgcat --position 0,0 banner.png
```

### Display multiple images in a grid

```bash theme={null}
for img in *.png; do
  wezterm imgcat --width 20 --height 10 "$img"
done
```

### Convert and display

```bash theme={null}
convert input.pdf[0] png:- | wezterm imgcat
```

### Screenshot and display

```bash theme={null}
# 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:

```bash theme={null}
wezterm imgcat animation.gif
```

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

## 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](/cli/set-working-directory) - Set terminal working directory
* [wezterm start](/cli/start) - Start a terminal session