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.

• Auto-detected protocols — Kitty, Sixel, half-block fallback. Works on any modern terminal.
• Multiple sources — local files, data: URIs (base64), and http(s):// URLs.
• 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.

go get github.com/floatpane/termimage

Requires Go 1.26+.

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)
    }
}

The src argument accepts any of:

termimage.Display(os.Stdout, "/path/to/cat.png", opts)
termimage.Display(os.Stdout, "https://example.com/cat.png", opts)
termimage.Display(os.Stdout, "data:image/png;base64,iVBORw0KGgo...", opts)

Remote URLs and data URIs are fetched/decoded in the parent process, then handed to the sandboxed worker over stdin — the worker still runs with Landlock denying all filesystem access. Remote payloads are capped at 64 MiB.

Use DisplayContext to pass a context.Context for cancellation of HTTP fetches and decoding.

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

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.

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

PRs welcome. See CONTRIBUTING.md.

Report vulnerabilities privately via SECURITY.md.

MIT. See LICENSE.