termimage

README

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.
• 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.

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

Sources

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.

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.

Documentation

Overview

Package termimage renders images in a terminal using Kitty graphics, Sixel, or Unicode half-block characters as fallback. Image decoding runs inside a sandboxed subprocess (Landlock + seccomp on Linux) so untrusted bytes never touch the parent process.

The consuming binary must call MaybeRunWorker() at the very top of main():

func main() {
    termimage.MaybeRunWorker()
    // ... rest of your app
}

Index

• Constants
• func Display(w io.Writer, src string, opts Options) error
• func DisplayContext(ctx context.Context, w io.Writer, src string, opts Options) error
• func MaybeRunWorker()
• type Options
• type Protocol

Constants

const (
	Auto      Protocol = -1
	HalfBlock          = detect.HalfBlock
	Sixel              = detect.Sixel
	Kitty              = detect.Kitty
)

Functions

func Display

func Display(w io.Writer, src string, opts Options) error

Display decodes the image at src and writes terminal graphics to w. src may be a local file path, a data: URI, or an http(s):// URL.

func DisplayContext

func DisplayContext(ctx context.Context, w io.Writer, src string, opts Options) error

DisplayContext is Display with caller-supplied context for cancellation of remote fetches and sandboxed decoding.

func MaybeRunWorker

func MaybeRunWorker()

MaybeRunWorker must be called at the top of main(). If this process was spawned as a sandbox worker it applies OS restrictions, decodes the image, writes pixels to stdout, and exits. Otherwise it returns immediately.

Types

type Options

type Options struct {
	// MaxWidth / MaxHeight in pixels. 0 = detect from terminal.
	MaxWidth, MaxHeight int

	// Protocol selects the rendering protocol. Auto detects from $TERM etc.
	Protocol Protocol

	// Sandboxed runs the decoder in a subprocess with Landlock + seccomp.
	// Requires the consuming binary to call MaybeRunWorker() in main().
	Sandboxed bool
}

Options configures image display.

type Protocol

type Protocol = detect.Protocol

Protocol selects a terminal rendering protocol.