Display images in your terminal using the kitty graphics protocol.
kittyview renders PNG, JPEG, SVG, and many other image formats directly in your terminal. It auto-detects terminal support and produces clean, chunked output that works with large images.
kittyview auto-detects support via environment variables. Confirmed compatible terminals:
Use --force if your terminal supports the protocol but isn't detected.
Download from GitHub Releases for Linux (amd64, aarch64), macOS (Intel, Apple Silicon), and Windows (amd64, aarch64). Linux binaries are statically linked.
cargo install --path .
# Display an image
kittyview photo.jpg
# Display an SVG diagram
kittyview architecture.svg
# Pipe from another tool
curl -s https://example.com/image.png | kittyview
dot -Tsvg graph.dot | kittyview
# Display the built-in logo
kittyview logo
When no file is given and stdin is piped, kittyview reads from stdin automatically. Format is detected from file contents (magic bytes for raster images, <svg for SVGs).
By default, animated GIFs display their first frame only. Use --animate to play the full animation via the kitty animation protocol:
# Play an animated GIF
kittyview --animate nyan.gif
# Animated logo with speech bubble
kittyview --animate logo
Animation support requires a terminal with kitty animation protocol support (currently kitty; Ghostty and others may show only the first frame).
The png subcommand exports any supported format as a PNG file, useful for debugging or format conversion:
# Convert SVG to PNG
kittyview png diagram.svg -o diagram.png
# Export the built-in logo
kittyview png --logo -o logo.png
# Pipe through
dot -Tsvg graph.dot | kittyview png -o graph.png
# Bash
kittyview completions bash > ~/.local/share/bash-completion/completions/kittyview
# Zsh
kittyview completions zsh > ~/.local/share/zsh/site-functions/_kittyview
# Fish
kittyview completions fish > ~/.config/fish/completions/kittyview.fish
| Format | Extensions |
|---|---|
| PNG | .png |
| JPEG | .jpg, .jpeg |
| GIF | .gif |
| SVG | .svg, .svgz (text rendering, see SVG notes) |
| WebP | .webp |
| BMP | .bmp |
| TIFF | .tif, .tiff |
| ICO | .ico |
| PNM | .ppm, .pgm, .pbm |
| TGA | .tga |
| QOI | .qoi |
| Farbfeld | .ff |
| HDR | .hdr |
SVG files are detected by extension or by content sniffing (<svg in the first 1KB).
kittyview renders SVGs using resvg, which supports native SVG <text> elements out of the box.
Many tools (mermaid-cli, draw.io, D3.js) generate SVGs that use <foreignObject> with embedded HTML for text labels instead of native <text> elements. kittyview detects these and converts them to <text> on a best-effort basis. This covers the common cases well, but has some limitations:
- Text wrapping: HTML text that relies on CSS word-wrap (without explicit
<br>tags) will render as a single line. Most mermaid diagrams use<br>and are unaffected. - Rich formatting: Bold, italic, and per-element font size or color differences inside labels are not preserved. The global font and color from the SVG's stylesheet are used.
- Structural HTML: Tables, lists, and nested divs are rendered as readable plain text (cells separated by tabs, rows and list items on separate lines) but without visual table/list formatting. MathML and form elements are not supported.
- Edge label backgrounds: Semi-transparent background rectangles behind edge labels are not reproduced.
SVGs that already use native <text> elements (e.g. Inkscape, some mermaid-cli configurations) render without these limitations.
When rendering SVGs, external file references (<image href="...">) are blocked by default. Use --svg-resources to control this:
| Policy | Allows |
|---|---|
none (default) |
Embedded/inline images only. No file access. |
cwd |
Files in the current working directory. |
tree |
Files in the current working directory and subdirectories. |
any |
Unrestricted file access. |
Data URLs (images embedded directly in the SVG) always work regardless of policy.
For file inputs, relative paths in the SVG resolve from the SVG file's directory. For stdin, they resolve from the current working directory.
# Render an SVG that references local images
kittyview --svg-resources tree diagram.svg
# Same via stdin -- relative paths resolve from CWD
cat diagram.svg | kittyview --svg-resources tree
- Terminal detection: kittyview refuses to emit escape sequences to non-terminal stdout or unsupported terminals unless
--forceis used. This prevents accidental binary output to files or pipes. - Stdin support: When no file is given and stdin is piped, kittyview reads from stdin. Format is detected from content, not filenames.
- SVG sandboxing: External file access from SVGs is blocked by default (
--svg-resources none). This applies to both file and stdin inputs. - SVG size limits: Oversized SVGs are automatically downscaled (max 8192x8192) to prevent memory exhaustion.
- Pure Rust: No C dependencies. The entire dependency tree compiles from Rust source.
- Crash safety: Kitty protocol output is fully buffered before writing to minimize partial escape sequences if the process is interrupted.
Requires Rust 1.87+ (edition 2024).
cargo build --release
Run tests:
cargo test
Apache-2.0