pypgfplots 0.1.8

Minimal pgfplots wrapper for marimo notebooks

pypgfplots

Minimal Python wrapper that renders pgfplots figures as high-quality PNG inside marimo notebooks. Figures are identical to what you would include in a LaTeX paper or slide deck — because they are LaTeX.

Requires a working LaTeX installation with pdflatex on $PATH, plus a PDF→PNG converter — install one of:

brew install poppler       # provides pdftoppm (recommended)
brew install mupdf-tools   # provides mutool
brew install imagemagick   # provides convert

Ghostscript (gs) is also accepted if already on $PATH.

---

Installation

From GitHub with uv (recommended)

uv add git+https://github.com/bjoseru/pypgfplots

Inside a marimo notebook

Add a cell at the top:

import subprocess
subprocess.run(["uv", "pip", "install", "git+https://github.com/bjoseru/pypgfplots"])

Or use marimo's package manager sidebar (requires uv backend).

Plain pip

pip install git+https://github.com/bjoseru/pypgfplots

---

Quick start

from pypgfplots import Axis

a = Axis(title="Parabola", xlabel=r"$x$", ylabel=r"$f(x)$")
a.addplot(r"x^2", color="red", domain="-2:2", samples=100)
a  # displays as PNG in marimo

Combine two axes side by side:

a = Axis(title="Left")
a.addplot(r"sin(deg(x))", domain="0:6.28")

b = Axis(title="Right", axis_lines="left")
b.addplot(r"cos(deg(x))", domain="0:6.28")

a + b  # renders both in one tikzpicture

Coordinate data

coords = " ".join(f"({x},{x**2})" for x in range(6))
a = Axis()
a.addplot(coords, _type="coordinates", mark="*", color="blue")
a

Table data

a = Axis()
a.addplot("data.csv", _type="table", col_sep="comma", x="time", y="value")
a

3-D plots

a = Axis()
a.addplot3(r"x^2 + y^2", domain="-2:2", samples=30)
a

Global settings

from pypgfplots import pgfplotset, preamble, classoptions

pgfplotset(compat="1.18")
preamble(r"\usepackage{amsmath}")
classoptions("border=5pt")

---

Export

a.save_pdf("figure.pdf")   # compile and write PDF
a.save_tex("figure.tex")   # write LaTeX source (no compilation)
src = a.latex()             # full standalone source as string
log = a.compile_log()       # pdflatex output of last run

---

Development

Clone the repo and install in editable mode:

git clone https://github.com/bjoseru/pypgfplots
cd pypgfplots
uv pip install -e .

Run the tests:

uv run --with pytest pytest

Tests that require pdflatex and a PDF→PNG converter are skipped automatically if those tools are not on $PATH. To run only the pure-Python unit tests:

uv run --with pytest pytest tests/test_core.py tests/test_options.py

---

Pipeline

Display:  Python API  →  .tex  →  pdflatex  →  PDF  →  pdftoppm  →  PNG  →  marimo
PDF:      Python API  →  .tex  →  pdflatex  →  PDF

The PNG is delivered via _repr_html_() and is therefore also usable in Jupyter.

---

License

MIT — see LICENSE.