---
name: "ueberzug"
section: "1"
platform: "linux"
package: "ueberzugpp"
version: "2.9.10-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ueberzug"
---

# ueberzug(1)

display images in a terminal

## NAME

ueberzugpp - display images in a terminal

## SYNOPSIS

**ueberzugpp** \[*options*\]

## DESCRIPTION

**ueberzugpp** is a program meant to display images in a terminal in a with an IPC.

## OPTIONS

- **-h**, **--help**

  Show help text.

- **--version**

  Show version

- **--use-escape-codes**

  Use escape codes to get terminal capabilities

- **--no-stdin**

  Do not listen on stdin for commands

- **--no-cache**

  Disable caching of resized images

- **--no-opencv**

  Do not use OpenCV, use Libvips instead

- **-o**, **--output**

  Image output method, valid values for this include:

*x11  (May not be available if disabled in compilation)*\
 *sixel*\
 *kitty*\
 *iterm2*\
 *wayland  (May not be available if disabled in compilation)*\
 *chafa*

- **-p**, **--parser**

  **UNUSED ,**  only present for backwards compatibility

- **-l**, **--loader**

  **UNUSED ,**  only present for backwards compatibility

## STDIN

Ueberzugpp reads commands through stdin. Or through the unix socket located at /tmp/ueberzug\_.sock

Commands should be in JSON form, as described in the JSON IPC section

## JSON IPC

There are two actions, *add* and *remove*

### **add**

action json schema

Requried Keys

- **action (string)**

  should be *add*

- **path (string)**

  the path to the image to use

- **identifier (string)**

  an identifier for the image, so that it can be removed with the remove action

- **One of, width/height, or max\_width/max\_height**

  - **width (integer)**

  width of the image

- **max\_width (integer)**

  maximum width of the image

- **height (integer)**

  height of the image

- **max\_height (integer)**

  maximum height of the image

- **x (integer)**

  the column position in the terminal

- **y (integer)**

  the row position in the terminal

Optional keys

- **scaler (string)**

  can be fit\_contain or forced\_cover.\
   Both base the scale on whichever is larger, the width, or height of the image

### **remove**

action json schema

Requried Keys

- **action (string)**

  should be remove

- **identifier (string)**

  The identifier of the image to remove

## EXAMPLE

Create a fifo file named fifo, and have an image in the current folder named image.png for this example to work

ueberzugpp layer -o sixel \< fifo &

echo '{"path": "./image.png", "action": "add", "identifier": "image", "x": 0, "y": 0, "width": 20, "height": 20}' \> fifo