Jupyter.Install

Before any Jupyter frontends (such as the notebook or console) can use a kernel, the kernel must be installed. Traditionally, kernels are installed by defining a kernelspec and running jupyter kernelspec install, where a kernelspec is defined by creating a directory with a set of predefined files that Jupyter knows how to handle, and is installed by passing the directory to jupyter kernelspec install. Installed kernelspecs may be queried with jupyter kernelspec list.

Instead, this module provides a few utilities for defining, installing, and locating kernelspecs. A kernelspec can be defined by creating a value of type Kernelspec and can be installed with installKernel. The installed kernelspecs may be listed or searched with findKernels and findKernel, respectively. These utilities are simply convenient wrappers around the jupyter kernelspec install and jupyter kernelspec list commands.

Kernelspec Definitions

data Kernelspec

A kernelspec is a description of a kernel which tells the Jupyter command-line application how to install the kernel and tells the frontends how to invoke the kernel (command line flags, environment, etc).

More documentation about kernelspecs is located in the official documentation.

Constructors

Kernelspec

Fields

kernelspecDisplayName :: Text

Name for the kernel to be shown in frontends, e.g. "Haskell".

kernelspecLanguage :: Text

Language name for the kernel, used to refer to this kernel (in command-line arguments, URLs, etc), e.g. "haskell".

kernelspecCommand :: FilePath -> FilePath -> [String]

How to invoke the kernel. Given the path to the currently running executable and connection file, this function should return the full command to invoke the kernel. For example:

\exe connectionFile -> [exe, "kernel", "--debug", "--connection-file", connectionFile]

kernelspecJsFile :: Maybe FilePath

(optional) path to a Javascript file (kernel.js) to provide to the Jupyter notebook. This file is loaded upon notebook startup.

kernelspecLogoFile :: Maybe FilePath

(optional) path to a 64x64 PNG file to display as the kernel logo in the notebook.

kernelspecEnv :: Map Text Text

Additional environment variables to set when invoking the kernel. If no additional environment variables are required, pass fromList [] or mempty.

simpleKernelspec

Arguments

:: Text

The kernel display name (see kernelspecDisplayName).

-> Text

The kernel language name (see kernelspecLanguage).

-> (FilePath -> FilePath -> [String])

The kernel command line invocation (see kernelspecCommand).

-> Kernelspec

Utility for creating simple kernelspecs, with all optional Kernelspec fields initialized to their empty values.

Example for Python 3: >>> simpleKernelspec "Python 3" "python3" $ exe0 connFile = ["python", "-m", "ipykernel", "-f", connFile]

Installing Jupyter Kernels

installKernel

Arguments

:: InstallUser

Whether the kernel should be installed for only the current user (with --user) or globally

-> Kernelspec

The kernelspec to install

-> IO InstallResult

Installation result, potentially with a friendly error message

Install a Kernelspec using jupyter kernelspec install.

This function expects the jupyter command to be on the user's PATH, and will fail if the jupyter command is either unavailable or is a version incompatible with this library.

More documentation about kernelspecs is located in the Jupyter documentation and by running jupyter kernelspec install --help.

data InstallUser

Whether to install the kernel globally or just for the current user.

This corresponds to the --user flag for jupyter kernelspec install.

Constructors

InstallLocal

Install this kernel just for this user.

InstallGlobal

Install this kernel globally.

Instances

Eq InstallUser

Ord InstallUser

Show InstallUser

data InstallResult

Whether the installation was successful.

Constructors

InstallSuccessful

Kernelspec installation was successful.

InstallFailed Text

Kernelspec installation failed, with the reason for failure provided.

Instances

Eq InstallResult

Ord InstallResult

Show InstallResult

Detecting Installed Kkernels

findKernel :: Text -> IO (Maybe Kernelspec)

Find the kernelspec for a kernel with a given language name.

If no such kernel exists, then Nothing is returned. If an error occurs while searching for Jupyter kernels, a JupyterKernelspecException is thrown.

findKernels :: IO [Kernelspec]

Find all kernelspecs that the Jupyter installation is aware of, using the jupyter kernelspec list command.

If an error occurs while searching for Jupyter kernels, a JupyterKernelspecException is thrown.