https://github.com/lusingander/lpx
Terminal Animated GIF Viewer 📽️
https://github.com/lusingander/lpx
animated-gif cli gif gif-animation gif-viewer image-viewer ratatui terminal tui
Last synced: 3 days ago
JSON representation
Terminal Animated GIF Viewer 📽️
- Host: GitHub
- URL: https://github.com/lusingander/lpx
- Owner: lusingander
- License: mit
- Created: 2026-03-25T08:27:07.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-29T01:11:45.000Z (about 2 months ago)
- Last Synced: 2026-04-29T02:34:09.606Z (about 2 months ago)
- Topics: animated-gif, cli, gif, gif-animation, gif-viewer, image-viewer, ratatui, terminal, tui
- Language: Rust
- Homepage:
- Size: 6.67 MB
- Stars: 24
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LPX
[](https://crates.io/crates/lpx)
Terminal Animated GIF Viewer 📽️
(Check out the [Screenshots](#screenshots) for more demos of how it works!)
## About
LPX is a tool for displaying GIF animations directly in the terminal.
It features the following capabilities:
- Image rendering using image display protocols (iTerm2, kitty)
- Interactive controls such as play, pause, and frame-by-frame stepping
- Loop playback of a selected range
- Flexible display modes, including full-screen and inline viewing
## Requirements
> [!WARNING]
> This tool requires a terminal emulator that supports following image protocols.
> It will not work in environments without these protocols, and there is no text-based fallback.
### Supported terminal emulators
The following image protocols are supported:
- [Inline Images Protocol (iTerm2)](https://iterm2.com/documentation-images.html)
- [Terminal graphics protocol (kitty)](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
Confirmed working terminal emulators are listed below. Other emulators supporting these protocols may also work, though they have not been explicitly tested.
#### Inline Images Protocol (iTerm2)
- [iTerm2](https://iterm2.com)
- [WezTerm](https://wezfurlong.org/wezterm/)
- [VSCode integrated terminal](https://code.visualstudio.com/docs/terminal/basics) \*1 \*2
\*1 Requires the [`terminal.integrated.enableImages` setting](https://code.visualstudio.com/docs/terminal/advanced#_image-support) to be enabled.
\*2 Any terminal emulator using [xterm.js](https://xtermjs.org) (like the VSCode terminal) may work if the [image display feature is enabled](https://github.com/xtermjs/xterm.js/tree/master/addons/addon-image).
#### Terminal graphics protocol (kitty)
- [kitty](https://sw.kovidgoyal.net/kitty/)
- [Ghostty](https://ghostty.org)
### Unsupported environments
- Sixel graphics is not supported.
- Terminal multiplexers (screen, tmux, Zellij, etc.) are not supported.
- Windows is not supported.
## Installation
### [Cargo](https://crates.io/crates/lpx)
```
$ cargo install --locked lpx
```
### [Homebrew](https://github.com/lusingander/homebrew-tap/blob/master/lpx.rb)
```
$ brew install lusingander/tap/lpx
```
### [AUR](https://aur.archlinux.org/packages/lpx)
```
$ paru -S lpx
```
### Downloading binary
You can download pre-compiled binaries from [releases](https://github.com/lusingander/lpx/releases).
## Usage
After installation, run the following command:
```
$ lpx path/to/your/image.gif
```
### Options
```
LPX - Terminal Animated GIF Viewer 📽️
Usage: lpx [OPTIONS]
Arguments:
Path to the image file
Options:
-p, --protocol Select the graphics protocol [default: auto] [possible values: auto, iterm, kitty]
-n, --frame-step Number of frames to skip per step action [default: 10]
-w, --max-width Limit the maximum width of the UI
-i, --inline Enable inline mode with the specified height in rows
-h, --help Print help
-V, --version Print version
```
### Keybindings
| Key | Description |
| ------------------------------------- | ------------------------------------------------ |
| q Esc Ctrl-C | Quit application |
| Space | Play / Pause |
| h / l or ← / → | Move to previous / next frame |
| H / L or Shift + ← / → | Move backward / forward by frame step count |
| 0 - 9 | Jump to percentage (0% to 90%) |
| j / k or ↓ / ↑ | Decrease / Increase playback speed |
| [ / ] | Set loop start / end point |
| C | Clear loop range |
| d | Toggle detailed information display |
## Screenshots
### Show detailed information
### Loop a specific range
### Change playback speed
### Inline mode
## License
MIT