A Common Lisp kernel for Jupyter along with a library for building Jupyter kernels.

View the Project on GitHub yitzchak/common-lisp-jupyter







Binder Quicklisp Build Status Build status

A Common Lisp kernel for Jupyter along with a library for building Jupyter kernels, based on Maxima-Jupyter by Robert Dodier which was based on cl-jupyter by Frederic Peschanski.

This file describes the installation and usage of common-lisp-jupyter on a local machine, but you can try out common-lisp-jupyter without installing anything by clicking on the Binder badge above.


In developing Maxima-Jupyter there were a number of enhancements and features added that cl-jupyter does not support. Because the structure of Maxima-Jupyter is significantly different from cl-jupyter back-porting these changes would probably be difficult. Therefore common-lisp-jupyter was created as library to support both Maxima-Jupyter and the included Common Lisp kernel. The library component handles all Jupyter messaging and most of the common kernel management tasks. This leaves only code evaluation and completion testing left to the derived kernel.


Comparison to cl-jupyter

In comparison to cl-jupyter the included kernel common-lisp has the following features.


common-lisp-jupyter may be installed on a machine using a local installation, a repo2docker installation, or via a Docker image.

Local Installation


Installing via Roswell

Installing via Quicklisp

Install Quicklisp and use (ql:add-to-init-file). If you already have Quicklisp installed you may need to update your distribution with (ql:update-dist "quicklisp") to resolve package conflicts.

Installing via Quicklisp [version 20190521 and earlier]

Install Quicklisp and use (ql:add-to-init-file). If you already have Quicklisp installed you may need to update your distribution with (ql:update-dist "quicklisp") to resolve package conflicts.

Start your Lisp implementation and evaluate the following. The install command will try to deduce the correct command line arguments for your implementation. The keyword parameters :bin-path and :ev-flag can be used to customize these arguments. For example, for SBCL :bin-path is sbcl and :ev-flag is --eval. To install a kernel image using uiop:dump-image use cl-jupyter:install-image instead of cl-jupyter:install. install-image takes no arguments.

(ql:quickload :common-lisp-jupyter)

Running common-lisp-jupyter

common-lisp-jupyter may be run from a local installation in console mode by the following.

jupyter console --kernel=common-lisp

Notebook mode is initiated by the following.

jupyter notebook

repo2docker Usage

common-lisp-jupyter may be run as a Docker image managed by repo2docker which will fetch the current code from GitHub and handle all the details of running the Jupyter Notebook server.

First you need to install repo2docker (sudo may be required)

pip install jupyter-repo2docker

Once repo2docker is installed then the following will build and start the server. Directions on accessing the server will be displayed once the image is built.

jupyter-repo2docker --user-id=1000 --user-name=jupyter

Docker Image

A prebuilt docker image is available via Docker Hub. This image maybe run run the following command.

docker run --network=host -it yitzchak/common-lisp-jupyter jupyter notebook --ip=

A local Docker image of common-lisp-jupyter may be built after this repo has been cloned using the following command (sudo may be required). This image is based on the docker image archlinux/base.

docker build --tag=common-lisp-jupyter .

After the image is built the console may be run with

docker run -it common-lisp-jupyter jupyter console --kernel=common-lisp

Writing Jupyter Kernels

New Jupyter kernels can be created by defining a new sub-class of jupyter:kernel and by defining methods for the generic functions jupyter:evaluate-code and jupyter:code-is-complete. For reference, please see cl-jupyter.lisp for the Common Lisp kernel that is included in the package.

The derived class of jupyter:kernel should initialize the following slots. Most of these slots are used to reply to kernel_info messages. Documentation for each can be found in the declaration of jupyter:kernel.

The method jupyter:evaluate-code should evaluate all code included in the input argument and return a list of evaluation results. Each result should be wrapped in an appropriate sub-class of jupyter:result. For instance, to return a S-Expr result one would call jupyter:make-lisp-result. jupyter:evaluate-code will be called with the package declared in the kernel class as the current default. For example, the Common Lisp kernel evaluates code in the COMMON-LISP-USER package.

The Jupyter message is_complete_request is also supported via the code-is-complete method. The return result should be one of allowed status messages, i.e. "complete", "incomplete", "invalid", or "unknown".

User level installation of kernels can be accomplished by a call to jupyter:install-kernel. cl-jupyter.lisp has an example of this call made during the installation phase of Roswell.