Termpix - Modern Terminal Image Display

Display images in the terminal using the best available protocol.

Features

Auto-detects terminal capabilities
Supports multiple protocols:
- Kitty Graphics Protocol (Kitty, WezTerm, Ghostty)
- Sixel (xterm, mlterm, foot, konsole, iTerm2)
- Überzug++ (modern X11/Wayland)
- w3mimgdisplay (legacy fallback)
Clean, simple API
Graceful fallbacks

Installation

gem install termpix

Or add to your Gemfile:

gem 'termpix'

Usage

require 'termpix'

# Create display instance (auto-detects best protocol)
display = Termpix::Display.new

# Show an image
display.show('path/to/image.png',
  x: 10,           # X position in terminal characters
  y: 5,            # Y position in terminal characters
  max_width: 80,   # Maximum width in characters
  max_height: 40)  # Maximum height in characters

# Clear the image
display.clear

# Check if images are supported
puts "Supported!" if display.supported?

# Get protocol info
info = display.info
puts "Using protocol: #{info[:protocol]}"

Force a Specific Protocol

# Force Kitty protocol
display = Termpix::Display.new(protocol: :kitty)

# Force Sixel
display = Termpix::Display.new(protocol: :sixel)

# Force w3m
display = Termpix::Display.new(protocol: :w3m)

Dependencies

ImageMagick (identify and/or convert commands)
For w3m/Überzug++: xwininfo and xdotool

Terminal Support

Kitty Protocol

Kitty
WezTerm
Ghostty
Konsole (partial)

Sixel

xterm (with -ti vt340)
mlterm
foot
WezTerm
iTerm2

w3m/Überzug++

Most X11 terminals
Wayland terminals (Überzug++ only)

License

Unlicense - Public Domain

Author

Geir Isene - https://isene.com