terminal-image
Display images and animated GIFs in the terminal using ANSI escape codes and native terminal protocols.
What is terminal-image?
terminal-image is a Node.js library that enables developers to display images and animated GIFs directly in terminal emulators. It solves the problem of visualizing image content in command-line interfaces by automatically detecting and using the best available terminal graphics protocol or falling back to ANSI block characters.
Node.js developers building CLI applications, tools, or scripts that need to display image previews, logos, or visual content within terminal environments.
Developers choose terminal-image for its zero-configuration protocol detection, support for animated GIFs, and universal compatibility across terminals—from modern graphics-capable emulators to basic ANSI environments.
Overview
Display images in the terminal
Use Cases
Best For
- Displaying image previews in CLI file managers or image utilities
- Adding visual branding (logos) to terminal-based applications
- Creating terminal-based image viewers or slideshows
- Showing animated progress indicators or status visuals in build tools
- Debugging image content directly in development workflows
- Building educational tools that visualize concepts in the terminal
Not Ideal For
- Web applications requiring browser-based image rendering
- Environments where only monochrome or text-only terminals are available
- Projects needing advanced image processing like filters or transformations
Pros & Cons
Pros
Automatically selects the best terminal protocol (Kitty, iTerm2, or ANSI) for optimal image quality, as detailed in the Terminal Protocol Support section.
Provides dedicated methods for GIFs with configurable frame rates and custom render handlers, enabling smooth animations in supported terminals.
Allows scaling by percentage of terminal dimensions or exact row/column counts, with optional aspect ratio preservation, as shown in usage examples.
Uses ANSI block characters with 24-bit color as a fallback, ensuring it works in any terminal that supports colors, per the README.
Cons
Only supports PNG, JPEG, and GIF; lacks modern formats like WebP or SVG, which could be a limitation for some use cases.
Maximum frame rate is capped at 30 FPS and ignored in iTerm, potentially affecting the smoothness of fast animations.
Image quality heavily depends on terminal capabilities; in basic terminals, the ANSI fallback produces lower-resolution block art.
Frequently Asked Questions
Related Projects
zxA tool for writing better scripts
Ink🌈 React for interactive command-line apps
chalk🖍 Terminal string styling done right
Inquirer.jsA collection of common interactive command line user interfaces.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.