https://github.com/floatpane/termimage
CGo library for displaying images in your terminal securely
https://github.com/floatpane/termimage
cli command-line go golang golang-library halfblock image-decoding image-processing image-viewer kitty-graphics quantization sandbox security sixel sixel-graphics stb-image terminal terminal-graphics terminal-image tui
Last synced: 11 days ago
JSON representation
CGo library for displaying images in your terminal securely
- Host: GitHub
- URL: https://github.com/floatpane/termimage
- Owner: floatpane
- License: mit
- Created: 2026-05-26T18:35:49.000Z (18 days ago)
- Default Branch: master
- Last Pushed: 2026-05-31T18:01:57.000Z (13 days ago)
- Last Synced: 2026-06-01T15:27:59.841Z (12 days ago)
- Topics: cli, command-line, go, golang, golang-library, halfblock, image-decoding, image-processing, image-viewer, kitty-graphics, quantization, sandbox, security, sixel, sixel-graphics, stb-image, terminal, terminal-graphics, terminal-image, tui
- Language: C++
- Homepage: https://termimage.floatpane.com
- Size: 148 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# termimage
**Render images in the terminal — Kitty, Sixel, or Unicode half-blocks — with a sandboxed decoder.**
[](https://golang.org)
[](https://pkg.go.dev/github.com/floatpane/termimage)
[](https://github.com/floatpane/termimage/releases)
[](https://github.com/floatpane/termimage/actions/workflows/ci.yml)
[](LICENSE)
`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
```bash
go get github.com/floatpane/termimage
```
Requires Go 1.26+.
## Usage
```go
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:
```go
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](https://pkg.go.dev/github.com/floatpane/termimage)
## Contributing
PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
## Security
Report vulnerabilities privately via [SECURITY.md](SECURITY.md).
## License
MIT. See [LICENSE](LICENSE).