gonum/plot: building plots in Go without leaving the language

What gonum/plot is for, and who ends up using it

gonum/plot is a Go library for building and drawing plots. The README describes it as the official fork of code.google.com/p/plotinum, which tells you where its lineage sits: it is not a new project chasing a trend, it is a continuation of an older Go plotting codebase. The audience is narrow and specific. If your program is written in Go and its output includes a chart, this library lets you construct that chart with Go values rather than shelling out to another process, generating a data file, and parsing an image back. There is no separate plotting language, no template file, and no runtime to embed.

The README notes that the API is still in flux and may change. That sentence matters more than most disclaimers. It means the package is intended for people who can absorb occasional breakage, not for teams that need a frozen interface across a decade. The repository is not archived, and the last push was on 2026-04-22, so the code is being touched, but the published statement about API churn is the honest signal about what adopting it costs.

A second audience is the one the README explicitly invites: people who write their own Plotter implementations. The plotter package ships a standard set, but the README points to a wiki tutorial on making custom plotters, and to a Community Plotters page for additional ones. If your chart type does not exist yet, the intended path is to write it rather than to wait for it.

The four packages and how a plot actually gets drawn

The README splits the project into four packages, and the split is the architecture. The plot package lays out a plot and provides primitives for drawing into it. The plotter package supplies Plotters, which use those primitives to draw lines, scatter plots, box plots and error bars. The plotutil package bundles a few routines that make common plot types quick to produce, and the README is candid that this package is new, less tested than the others, and bound to change. The vg package is the layer underneath everything: a generic vector graphics API that sits on top of back-ends, which the README lists as a custom EPS back-end, draw2d, SVGo, X-Window, gopdf and Gio.

That last list is the part worth reading twice, because it determines what you can get out of the library. SVG comes through ajstarks/svgo, PDF through codeberg.org/go-pdf/fpdf, and image handling through golang.org/x/image, all of which appear in go.mod. Gio is the route to on-screen output. The data flow is therefore: your Go values go into a plot, Plotters draw into it using plot's primitives, and the result is rendered through a vg back-end to whatever format that back-end produces. Nothing in this chain is declarative. You are assembling an object graph in code.

The top-level repository also contains directories that hint at the supporting machinery: font, palette, text, cmpimg, gob and testdata. The cmpimg directory in particular is the kind of thing a plotting library needs, since comparing rendered images is how you test drawing code without asserting on pixels by hand.

Installing gonum/plot and drawing a first plot

The README gives one installation instruction: use go get. The ellipsis at the end pulls in the subpackages as well as the root package.

go get gonum.org/v1/plot/...

After that command completes, the module is available under the import path gonum.org/v1/plot. Note that go.mod declares go 1.25.0, so an older toolchain will refuse to build it. The README does not walk through a first program, so the shape of one has to be assembled from the package descriptions: create a plot, add a Plotter from the plotter package, and save it through a vg back-end. The README points to the wiki for example plots and to pkg.go.dev for the API reference, and those are the two places to look for a complete working example rather than guessing at field names.

For a quick start, plotutil is the package the README describes as making common plot types very easy to produce, with the caveat that it is the least tested of the four. If you want the most predictable behaviour, start with plot and plotter directly and treat plotutil as a convenience you can drop later. There is no CLI in this repository. The tools directory and the tool block in go.mod reference goimports, check-copyright and check-imports, which are development utilities for the project itself, not user-facing commands.

Where gonum/plot stops being the right tool

The README's own warning is the first limitation: the API is in flux and may change. For a library that a long-lived service depends on, that is a real cost, and it is stated by the project rather than inferred. Pin your version and expect to do work at upgrade time.

The second limitation is the absence of a declarative layer. There is no grammar of graphics here, no way to describe a chart as data and let the library decide the rest. Every axis, legend and label is placed by code. The repository does contain legend.go, axis.go and labelling.go, so the pieces exist, but you are the one composing them. If your team includes people who think in terms of chart specifications rather than Go structs, this library will feel like the wrong level of abstraction.

The third is output. The back-ends listed in the README produce files or draw through Gio. If you need a browser-embedded interactive chart with tooltips and zoom, the SVG back-end gives you a static file, and the README documents nothing about interactivity. Plotting for a web front end is a case where a JavaScript charting library is the better choice, and gonum/plot is not competing there.

Finally, plotutil carries its own caveat. The README says it is quite new, not as well tested as the others, and bound to change. Building a production pipeline on it means accepting that specific risk.

How it compares with the alternatives people actually name

The related searches around this project include Vicanso/go-charts, which is the useful comparison because it is another Go charting option rather than a different language. The difference in approach is where the chart definition lives. go-charts is built around chart configuration and rendering, closer to the declarative end, while gonum/plot gives you primitives and Plotters and expects you to assemble the plot yourself. If you want to describe a chart and get an image, the configuration-driven style is less code. If you want a chart type nobody has implemented, gonum/plot's Plotter interface is the extension point, and the README explicitly documents writing your own.

The other comparison the search data surfaces is with Python plotting, which people reach for because the ecosystem is larger and the syntax is shorter. That is a real difference, but it is a language boundary, not a library one. The reason to choose gonum/plot is that the chart is produced by the same Go binary that produced the data, with no Python environment, no subprocess, and no serialization step in between. When that matters, the comparison with Python stops being relevant.

Against gnuplot, which also appears in the search data, the split is similar but sharper. gnuplot is a separate program with its own command language, driven by files or pipes. gonum/plot is a library inside your process. If you already have gnuplot in your pipeline and it works, there is no reason to move.

Versioning, licence and what upgrades cost

The repository is licensed BSD-3-Clause, which is a permissive licence and is the same family used across the Gonum organisation. That is a statement about the licence text, not legal advice; if your organisation has licence policy, run it through that. The practical implication of a permissive licence is that you can vendor or embed the library without the copyleft obligations a GPL would impose.

The release cadence visible in the release list is uneven. v0.16.0 was released on 2025-03-27, v0.15.0 on 2024-10-22, and v0.13.0 on 2023-05-12. There is a gap in the list, and the spacing between the three entries is roughly five months, then seventeen months. The version numbers are still v0.x, which is consistent with the README's statement that the API may change. Treat every minor bump as a potential breaking change and read the release notes rather than assuming compatibility.

The dependency list in go.mod is another upgrade cost. The library pulls in gonum.org/v1/gonum, golang.org/x/image, and font packages from codeberg.org, along with several indirect dependencies. A Go module upgrade of gonum/plot can therefore move your gonum version too, which may affect numerical code elsewhere in your program. That is the kind of coupling worth checking before a bump, not after.

Editorial conclusion

Adopt gonum/plot when the chart has to be produced inside a Go program and written to a file, and when you are willing to pin a version because the README states the API is still in flux. Do not adopt it if you need interactive windows, a grammar-of-graphics style declarative layer, or a stable API contract across releases. Verify first that the back-end you need is covered by the vg package, that your Go toolchain satisfies the go 1.25.0 directive in go.mod, and that the fonts you intend to use are among the bundled font packages.

Frequently asked questions

Official sources

1. gonum/plot on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases