gophernotes: a Go kernel for Jupyter, built on the gomacro interpreter

The gap gophernotes fills between Go and the notebook interface

Jupyter notebooks are language agnostic at the protocol level and language specific in practice. The kernel is the piece that decides which language a notebook cell runs. gophernotes is that piece for Go. The README describes it as a Go kernel for Jupyter notebooks and nteract, letting you use Go interactively in a browser-based notebook or desktop app, and share documents containing live Go code, equations, visualizations and explanatory text. The intended audience is a Go programmer who wants the notebook format for exploratory work, demonstrations or teaching, without switching to Python. The repository topics list data science, machine learning and numerical methods alongside golang and jupyter, which reflects the framing rather than a claim about bundled libraries. Nothing in the material suggests gophernotes ships numerical or plotting packages of its own; you bring whatever Go code you want to evaluate.

How the kernel evaluates a cell: gomacro under the Jupyter protocol

The mechanism is a two-layer arrangement. gophernotes speaks the Jupyter kernel protocol on one side and delegates evaluation to gomacro on the other. The README states plainly that the project utilizes a Go interpreter called gomacro under the hood to evaluate Go code interactively. That word, interpreter, is the important one. A normal Go program is compiled ahead of time by the toolchain. Here, cell contents are handed to gomacro, which evaluates them in a session that persists across cells. This is what makes interactive definition of a function in one cell and its use in the next cell possible at all, and it is also why the semantics of a notebook session are not identical to those of a compiled binary. The kernel process itself is started by Jupyter and receives a connection file path as its argument. The README shows the expected behaviour when the binary is run with no argument: it logs Need a command line argument specifying the connection file. That message is the clearest single confirmation that the binary is installed and reachable.

Installing the kernel and what kernel.json actually does

Installation is two steps: build the binary, then register a kernel directory that Jupyter will discover. On Linux and FreeBSD the quick path is go install github.com/gopherdata/gophernotes@v0.7.5, followed by creating ~/.local/share/jupyter/kernels/gophernotes, copying the contents of the kernel directory from the module cache into it, making kernel.json writable, and rewriting the placeholder with sed so that it points at the real binary path under $(go env GOPATH)/bin. On macOS the same sequence targets ~/Library/Jupyter/kernels/gophernotes. The manual alternative clones the repository, checks out the v0.7.5 tag, runs go install, and copies kernel/* into the kernel directory. The sed step exists because the shipped kernel.json.in contains the bare name gophernotes rather than an absolute path; if you skip it, Jupyter may fail to launch the kernel depending on your PATH. The README also warns that if JUPYTER_PATH is set, or if you are on an older Jupyter, the config may need to go elsewhere, and points at jupyter --data-dir to list the directories that will be searched. Windows uses %APPDATA%\jupyter\kernels\gophernotes and an xcopy of the kernel folder. A Docker install is offered as an alternative for that platform.

The plugin package constraint on macOS and Windows

The most concrete limitation in the README concerns third party imports. gomacro relies on the Go plugin package when importing third party libraries. On macOS the README says this works reliably with Go 1.10.2 or later as long as you never run strip gophernotes, which is an unusual and easily violated constraint: any packaging or CI step that strips binaries will break third party imports in the notebook. On Windows the situation is sharper. The README states that the plugin package is only supported on Linux and macOS, so if you need third party packages in Go notebooks on Windows, the documented answer is to run gophernotes and Jupyter inside Docker instead. That is a real architectural boundary, not a rough edge. It means the native Windows install is effectively limited to the standard library and whatever gomacro can handle without plugin loading.

Where gophernotes is the wrong tool

If your notebook work depends on the Python scientific stack, gophernotes will not substitute for it. There is no mention in the material of an equivalent plotting layer, dataframe library, or array package shipped with the kernel. The example notebooks listed in the README cover worker pools, matrix operations, facial recognition through MachineBox, and display of images, HTML and LaTeX, which suggests the display protocol is supported, but the computational content comes from the Go code you write or import. A second case where gophernotes is the wrong choice is any workflow that expects compiled-binary semantics. Because evaluation goes through an interpreter, code that relies on the full build pipeline, on cgo in ways gomacro does not handle, or on build tags selected at compile time may not behave as it does in a normal go build. The README does not enumerate which language features gomacro supports, so that boundary has to be found empirically. Third, the release history is worth noting: the most recent release listed is v0.7.5 from May 2022, while the repository itself shows a push in September 2026. Kernel installs are pinned to a tagged version in the documented commands, so you are installing a release that is several years old even if the master branch has moved.

The alternative: a Python kernel with Go called as a subprocess

A common alternative is to keep the default Python kernel and treat Go as an external program, either by shelling out from a cell or by exposing Go functionality behind an HTTP or RPC service that Python calls. The difference in approach is fundamental. With gophernotes, the notebook cell is Go, evaluated in-process by gomacro, so state lives in the kernel session and you get Go syntax, Go types and Go error handling directly in the cell. With the subprocess approach, the notebook cell is Python, and Go code is a compiled artifact invoked across a process boundary; you get the full Go compiler and its plugin-free build model, at the cost of marshalling data in and out and losing interactive Go state. If you need the plugin package to work on Windows, or you need constructs gomacro does not interpret, the subprocess route avoids both problems. If you want the notebook to read as Go, gophernotes is the only one of the two that gives you that.

Maintenance cost and the MIT licence

The upkeep burden here is modest but not zero. The kernel directory contains a kernel.json whose binary path is written at install time, so moving your GOPATH, reinstalling Go, or upgrading the module version means regenerating that file with the same sed command. Upgrading means repeating the install steps for a new tag, since the documented commands pin an explicit version such as @v0.7.5. The macOS strip constraint is a standing rule that has to be communicated to anyone who packages the binary. On the licence side, gophernotes is MIT, which is permissive and places few obligations beyond retaining the copyright notice and licence text. gomacro, the interpreter it depends on, is a separate project with its own licence, and the material provided here does not state what that licence is; check it before redistributing a combined artifact. This is a description of the licence identifiers, not legal advice.

Editorial conclusion

Adopt gophernotes if you already write Go and want an interactive notebook front end for it, and you are willing to install a Jupyter kernel directory by hand. Do not adopt it if you need third party packages on Windows without Docker, or if your work depends on the numerical and plotting ecosystem that Python kernels provide. Before committing, verify two things on your own machine: that the gophernotes binary prints the connection file message when run directly from GOPATH, and that importing one third party package works in a cell on your target OS, since the plugin package behaviour differs between macOS, Linux and Windows.

Official sources

1. gopherdata/gophernotes on GitHub
2. Issues
3. License: MIT
4. README
5. Releases