Gonum: numeric libraries for Go, from matrices to graph algorithms

What Gonum solves, and the Go programmers it targets

Go ships with a small standard library for numbers. There is no matrix type, no distribution functions, no optimizer. A service that needs to solve a linear system, fit a regression or run a graph traversal either shells out to another language or grows its own half-tested numeric code. Gonum exists to fill that gap inside Go itself. The README describes it as "a set of numeric libraries for the Go programming language" containing "libraries for matrices, statistics, optimization, and more", and the repository layout backs that up: mat, stat, optimize, integrate, interp, spatial, graph, floats and unit.

The intended user is a Go developer who wants numerics as a library dependency rather than as a separate runtime. Because the core packages are written in pure Go with some assembly, a Gonum program cross-compiles and deploys like any other Go binary. That matters for teams running numeric code inside an HTTP service, a CLI tool or a batch job where pulling in a C toolchain or a Python interpreter is unwanted. It is not aimed at analysts who want to poke at a dataset in a notebook; nothing in the repository is an interactive environment.

How the Gonum packages fit together: mat, stat, optimize and graph

Gonum is a module, not a single library. Import paths are rooted at gonum.org/v1/gonum, and each top-level directory is an independent package with its own API surface. The mat package holds dense and sparse matrix types and the decompositions built on them. stat holds distribution and statistics routines. optimize holds function minimization. integrate and interp cover numerical integration and interpolation. graph holds graph representations plus algorithms, with subpackages for formats such as DOT and RDF.

The dependency direction is the interesting part. The repository is a single Go module, so the packages share one version and one go.mod, but they are not one monolith: a program that only needs distributions does not have to touch mat. That is a deliberate trade-off. You get consistent versioning across the suite, and you accept that upgrading one package moves the whole module forward.

The README also notes that floating point behaviour may differ between compiler versions and between architectures, because of differences in how floating point operations are implemented. That is not a defect in Gonum; it is a property of the platform, and it is worth knowing before you write golden-value tests against numeric output.

Installing Gonum and running a first matrix computation

Installation is done with go get, as the README states. The command below is the one the README gives. Run it inside a Go module, and expect the dependency to appear in go.mod afterwards.

go get -u gonum.org/v1/gonum/...

The README lists the supported toolchains as the two most recent Go releases, tested with the gc compiler on Linux (386, amd64 and arm64), macOS, and Windows on amd64. Check your own version before going further; a Gonum build on an older toolchain is outside what the project tests.

For a first real use, the natural entry point is the mat package, whose import path is gonum.org/v1/gonum/mat and which the README names as part of the suite's matrix support. The Go module file in the repository records the module path as gonum.org/v1/gonum, so that is the prefix every import in a Gonum program starts with. The README itself does not print a worked matrix example; the runnable examples live in the package documentation, which the README links to through its go.dev reference badge. Start there rather than guessing at method names, because the mat API uses receiver-as-destination calls where the result is written into a matrix you allocate yourself, and that convention is not obvious from the type names alone.

Build tags, assembly and the limits of a pure Go numeric stack

The README documents four non-internal build tags: safe, which avoids assembly and unsafe; bounds, which keeps bounds checks even in internal calls; noasm, which disables assembly implementations; and tomita, which selects the Tomita, Tanaka, Takahashi pivot choice for maximal clique calculation in the topo package, with a random pivot used otherwise. Building an application works without knowing any of this, but the tags are how you trade speed for auditability or portability.

That is the honest limitation of Gonum. The default build leans on assembly for speed, and the escape hatches exist precisely because assembly is not always what you want: on an unusual architecture, in a security-sensitive context, or when you need reproducible behaviour across machines. Turning on safe or noasm gives you a build you can reason about, at a cost the README does not quantify. Anyone who needs that number has to measure it themselves.

The other limitation is scope. Gonum is a numeric library, not a data analysis environment. There is no dataframe abstraction, no plotting in the core module, and no model catalogue. The dependency list in go.mod includes gonum.org/v1/plot, but that is a separate module with its own release cadence. If your work is exploratory rather than programmatic, Gonum will feel like the wrong shape.

Gonum versus NumPy: same arithmetic, different workflow

The comparison people search for is gonum vs numpy, and the useful answer is about workflow rather than raw arithmetic. NumPy is the array layer of a Python ecosystem that also provides pandas, SciPy, scikit-learn and a notebook. You get a REPL, immediate feedback, and a large body of third-party models. Gonum gives you a Go module you import into a compiled program. There is no interpreter, no cell-by-cell execution, and no ecosystem of equivalent breadth.

What you get in exchange is deployment. A Gonum binary is a Go binary: one artifact, cross-compiled, with no Python runtime and no virtual environment to reproduce. For a service that computes a small matrix inverse per request, or a CLI that runs an optimization, that difference is the whole argument. For a research script where the model choice changes weekly, it is a strong argument against.

Gonum also spans ground NumPy does not: the graph packages, including format parsers for DOT and RDF, live in the same repository as the linear algebra. If your problem is graph-shaped with some statistics attached, that combination is hard to assemble elsewhere in Go.

Release cadence, licence and the cost of staying current

Gonum follows a six-month release schedule aligned with Go: Gonum-v0.n.0 lands around February, and Gonum-v0.n+1.0 around August, following the Go releases. The recent tags match that rhythm, with v0.17.0 in January 2026 after v0.16.0 in March 2025. The last push to the repository was on 2026-08-30, so the project is not dormant, but the README carries a stability badge reading unstable, which is the maintainers' own description of the API surface rather than a comment on code quality.

That badge is the upgrade cost in one word. Because the whole suite shares a single module, moving to a new minor version moves mat, stat, optimize and graph together. A program that depends on several of them cannot upgrade one at a time. Plan for periodic, coordinated version bumps rather than piecemeal updates, and read the release notes before each one.

On licensing, the README states that original code is under the Gonum License found in the LICENSE file, and that portions are subject to additional licences in THIRD_PARTY_LICENSES, all of which are BSD or MIT. Code in graph/formats/dot is dual licensed under a Public Domain Dedication and the Gonum License, and the W3C test suites in graph/formats/rdf carry the W3C Test Suite License and the W3C 3-clause BSD License. If your organisation has rules about which licences may enter a product, that dual-licensed DOT package is the one to read carefully before you ship it.

Editorial conclusion

Adopt Gonum if your numerics already live inside a Go program and you want one dependency tree, a pure Go build, and packages such as mat, stat, optimize and graph under a single module. Do not adopt it if you need an interactive notebook, a wide catalogue of statistical models, or plotting inside the library itself; gonum.org/v1/plot is a separate module listed in go.mod. Before committing, verify that your target Go toolchain is one of the two most recent releases the README says are tested, and check whether the safe, noasm or bounds build tags change the behaviour you depend on, since floating point results may differ between compiler versions and architectures.

Frequently asked questions

Official sources

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