Images That Behave Like Text

Showing an image in a terminal looks easy. A program prints some bytes and a picture appears. The hard part starts one second later, when you scroll, resize the window, split a pane, clear a line, or open an editor that draws its own windows on top.

That is where image support tends to break: pictures that pile up copies of themselves, get holes where you erased a line, or stay on screen after the program removed them. Earlier Nash releases had these problems too.

Nash 0.8.1 rebuilt its Kitty graphics protocol support around one idea: an image should behave like text. It moves with its lines, it goes away when its program says so, and one image never disturbs another.

What You Will Notice

If you use a tool that previews images in your terminal, such as Neovim image previews, the pictures are steadier. Specifically:

• Overlapping images stack correctly. They are ordered by z-index, then by image id. A new placement no longer copies the slices of the image under it, so the garbled, mixed pictures are gone.
• Erasing text leaves images whole. Clearing part of a line or part of the screen no longer cuts holes into a picture. Clearing the whole screen removes the pictures on it, as you expect.
• Deleting one picture leaves the others alone. Each placement is tracked on its own, so removing one no longer takes its siblings with it.
• Full-screen programs keep their own images. The primary screen and the alternate screen each have separate pictures. Quitting an editor does not wipe or change what your shell showed.
• Images follow their lines. Scrolling, scroll regions, and the scrollback all carry the picture along, and they keep their position and stacking order when a resize rewraps the text.
• Wide text is safe. An image under CJK characters or emoji no longer turns the text into spaces or repeats a slice of the picture.

Images Inside Editors and tmux

Some programs cannot place an image by moving the cursor. An editor that draws windows and floating panels needs the picture to move, scroll, and clip together with the text around it.

Nash 0.8.1 supports Unicode placeholders for exactly that. The program draws a special placeholder character in each cell, and Nash fills the cells with the matching tile of the image. Because the picture's position is ordinary text, it follows every edit of that text. This is how the snacks.nvim Neovim plugin shows images inside windows and floats, and how programs place images inside tmux.

Nash also answers capability queries. A program asks "can you show images?" and gets a clear OK, or an error if its request is malformed. Programs that check before they draw can now pick the right mode on their own.

Try It in a Minute

You need Nash 0.8.1 or newer. Point the command at any PNG file:

Nash draws the picture 20 cells wide and keeps its aspect ratio. Then print some lines so it scrolls away, resize the window, or run clear, and watch it behave like text.

For a one-line check without escape sequences, use nash imgcat:

What It Does Not Do

We would rather tell you the limits than let you find them.

• Animation control is not supported. A program can send animation frames, but it cannot start, stop, or loop an animation.
• A failed command gets no error reply. Nash logs the reason, and a program that waits for a reply waits for its own timeout. The troubleshooting guide explains where to find the log lines.
• There are size limits. Nash ignores an image larger than 100 MB once decoded, and it frees unused images when stored image data goes over 320 MiB.
• Multiplexer users need one restart. Nash 0.8.1 changed the multiplexer protocol to version 48, so a server from an older release must be restarted. A restart closes the panes the server owns, so pick a good moment.

Update and Read More

Run nash update, or get the latest build from the download page. If you use the multiplexer, check nash mux status first.

The Kitty Graphics Protocol guide has every supported key, the delete modes, how Unicode placeholders work, and the differences from kitty. For nash imgcat and sixel images, see Other Image Protocols.

---

A picture in your terminal should be as easy to trust as the text next to it.

-Nash Team