matplotlib-backend-nvim

A backend for displaying plots in neovim terminals

This python module allows you to use your terminal to show inline plots generated by python's matplotlib using the terminal-image.nvim plugin in neovim.

The module is a modified version of the kitty backend and is also based on this sixel backend.

You will need a terminal that can display images using the snacks image plugin.

To install either run

• $ pip install git+https://github.com/ctorney/matplotlib-backend-nvim.git

or clone this repo and run

• $ cd matplotlib-backend-nvim && pip install .

Configure matplotlib to use the module by either setting the environment variable MPLBACKEND to module://matplotlib-backend-nvim or by initializing matplotlib as follows.

import matplotlib
matplotlib.use('module://matplotlib-backend-nvim')
import matplotlib.pyplot as plt

To enable transparency in the terminal, you can set the MPLBACKEND_TRANSPARENT environment variable to 1. This will make the background of the plot transparent, allowing the terminal background to show through.

If you've installed this module correctly, you can now use the following sample code to draw a plot in your terminal.

import matplotlib
matplotlib.use('module://matplotlib-backend-nvim')
import numpy as np
import matplotlib.pyplot as plt
plt.style.use("dark_background")
t = np.linspace(0,5,200)
plt.fill_between(t,np.sin(t),np.cos(2*t),alpha=0.5)
plt.fill_between(t,np.cos(t),np.sin(2*t),alpha=0.5)
plt.show()

<plot is shown>

Example output using Ghostty terminal.

If you set your matplotlib to interactive mode via matplotlib.pyplot.ion() or by running python as python -i, non-empty figures are drawn on construction where possible. This allows you to use pandas' plot() calls directly, without calling plt.show(), and still enables you to manually construct and plt.show().

If your matplotlib is in non-interactive mode, you can construct your figures as usual, and then call plt.show() to render them to your terminal. This works from both a repl and when running scripts.

Internally, this backend is somewhat based on matplotlib's IPython support: it's a hybrid of image and GUI backend types. It works by using matplotlib's Agg backend to render the plot, and then uses the plugin to display in the terminal. This means that plotting works as

expected, but the image drawn to your terminal isn't interactive and animations aren't supported.