This project introduces a new kitcat backend for Matplotlib that allows plots to be displayed directly in the terminal. It utilizes the "agg" backend for rendering plots before sending them to the terminal.
- Direct Matplotlib plotting in terminal emulators that support Kitty or iTerm2 graphics protocols.
- Works seamlessly over SSH and inside tmux.
pip install kitcat
Select kitcat backend after importing matplotlib:
import matplotlib
matplotlib.use("kitcat")or if pyplot is already imported, switch_backend() can be used to select kitcat backend:
import matplotlib.pyplot as plt
plt.switch_backend("module://kitcat")Kitty and Ghostty are the recommended terminals. They implement modern protocol which let kitcat embed the image into the terminal's text buffer rather than overlaying it on the screen. This means plots scroll with the buffer, clip correctly at pane boundaries, and behave properly inside tmux — see tmux notes. Other supported terminals still work, but the image is drawn at a fixed screen position and won't track the buffer as cleanly.
| Terminal Emulator | Supported | Notes |
|---|---|---|
| Kitty | ✅✨ | |
| Ghostty | ✅✨ | |
| iTerm2 | ✅ | |
| VSCode | ✅ | Requires terminal.integrated.enableImages in settings |
| WezTerm | ✅ | |
| tmux | ✅ | See tmux notes |
| Warp | ✅ | |
| wayst | ✅ | |
| st | ✅ | Requires st-kitty-graphics patch |
| Zellij | ❌ | |
| Alacritty | ❌ | |
| Terminal.app (macOS) | ❌ |
On Kitty and Ghostty, kitcat uses Unicode placeholders so the image becomes part of tmux's text buffer — it scrolls with the buffer, clips at the pane boundary, and disappears when the pane is hidden. On other terminals, the image is drawn directly by the outer emulator and stays at a fixed screen position (so it can persist when switching panes — this is a tmux/terminal limitation, not a kitcat one).
Either way, set -g allow-passthrough on is required in your tmux config.
I discovered matplotlib-backend-kitty repository, which provides similar functionality in Kitty. I aimed to create a simpler solution that works across any terminal supporting the protocol.