termimage

Render images in the terminal — Kitty, Sixel, or Unicode half-blocks — with a sandboxed decoder.

termimage is a small Go library that displays images in a terminal. It auto-detects the best supported protocol (Kitty graphics, DEC Sixel, or Unicode half-blocks as fallback) and decodes images in a sandboxed subprocess (Landlock + seccomp on Linux) so untrusted bytes never touch the parent process.

Features

• Auto-detected protocols — Kitty, Sixel, half-block fallback. Works on any modern terminal.
• Sandboxed decoder — image bytes parsed in an isolated subprocess with Landlock + seccomp on Linux.
• No CGO required for the consumer — pure-Go API surface; the C decoder is contained in the worker subprocess.
• Terminal pixel detection — sizes output to the actual cell pixel dimensions when available.

Install

go get github.com/floatpane/termimage

Requires Go 1.26+.

Usage

package main

import (
    "os"

    "github.com/floatpane/termimage"
)

func main() {
    // Required: must be the first call in main() so sandbox workers can
    // re-exec into the decoder without running the rest of your program.
    termimage.MaybeRunWorker()

    err := termimage.Display(os.Stdout, "cat.png", termimage.Options{
        Protocol:  termimage.Auto,
        Sandboxed: true,
    })
    if err != nil {
        panic(err)
    }
}

Options

Field	Description
MaxWidth, MaxHeight	Pixel bounds. 0 = detect from terminal.
Protocol	Auto, Kitty, Sixel, or HalfBlock.
Sandboxed	Decode in a Landlock + seccomp subprocess.

Protocol detection

detect.Best() inspects $TERM, $TERM_PROGRAM, and $KITTY_WINDOW_ID. No ANSI queries are sent, so it works without a TTY.

Terminal	Protocol
kitty, Ghostty, WezTerm	Kitty graphics
foot, mlterm, Contour, xterm-sixel	Sixel
everything else	half-block

Sandbox

On Linux, the worker subprocess applies:

• Landlock — restricts filesystem access to the single image path.
• seccomp-bpf — blocks syscalls outside a read/decode allowlist.

On other platforms, the worker runs without OS-level restrictions but is still process-isolated.

Documentation

Full API reference: pkg.go.dev/github.com/floatpane/termimage

Contributing

PRs welcome. See CONTRIBUTING.md.

Security

Report vulnerabilities privately via SECURITY.md.

License

MIT. See LICENSE.