Tutorial
Images in the terminal
Sinclair renders sixel and kitty graphics: programs print an escape sequence, and an actual image appears in the grid — composited on the GPU, anchored to the text it arrived with, scrolling away with the rest of your output. File previews, plots, thumbnails, QR codes: if a tool can speak either protocol, it draws right in your terminal. This walkthrough renders your first image, explains how tools detect support automatically, and wires up a couple of everyday uses.
1. Render your first image
Grab either of the two standard converters and point it at any image:
# with libsixel
brew install libsixel # apt/dnf: libsixel-bin
img2sixel photo.png
# or with chafa
brew install chafa
chafa -f sixels photo.png
The image prints like output — because it is output. Run it again, scroll
back, and both copies are exactly where they happened in the history. Since sixel is
just bytes on the wire, this works over ssh too: run
img2sixel on a remote host and the picture renders in your local
Sinclair.
2. How tools know they can do this
You don't have to configure anything. Sinclair advertises sixel in its
DA1 (Primary Device Attributes) response and answers
XTSMGRAPHICS and XTWINOPS queries, which report
the pixel dimensions of the cell grid. Programs that probe the terminal — the way
notcurses, timg, or matplotlib's terminal backends do —
light up sixel support on their own and size images to your actual cells.
Sinclair speaks sixel and the common case of the
kitty graphics protocol. Tools that support several backends
usually pick one automatically from DA1; if one needs a hint, look for a
--format sixel or similar flag. Sixel images up to 10,000 px per
side (8 megapixels total) are accepted.
For kitty graphics, the supported shape is direct transmission: base64 payloads
in RGB (f=24), RGBA (f=32), or PNG (f=100),
optionally zlib-compressed (o=z) and split across chunks
(m=1), with transmit, display, delete, and query all answered. Images
land in the grid through the same compositor as sixel, so they scroll with the text
they arrived with. Not yet supported: transmission by file path or shared memory,
animation frames, unicode placeholders, and z-index/cropping — a tool relying on
those should be pointed at sixel instead.
3. Previews in your file manager
Terminal file managers make the best everyday use of this. yazi shows
sixel previews out of the box when the terminal advertises support. For
lf or ranger, set the previewer to chafa -f
sixels and browsing a directory of screenshots becomes an image gallery —
without leaving the keyboard.
4. Plot from Python
For quick data exploration, a sixel matplotlib backend (e.g.
matplotlib-backend-sixel) prints figures straight into the session:
pip install matplotlib-backend-sixel
python -c "
import matplotlib; matplotlib.use('module://matplotlib_backend_sixel')
import matplotlib.pyplot as plt
plt.plot([1, 4, 2, 8, 5]); plt.title('right here in the terminal'); plt.show()
"The figure appears inline, scrolls with your session, and is captured in the scrollback next to the code that produced it — a lab notebook for free.
Recording with ⌘⇧R captures the raw session — and that includes the sixel escapes. Playback through a sixel-capable player reproduces the images, pictures and all.