Skip to main content

Kotlin kernel for Jupyter notebooks

Project description

JetBrains official project Kotlin beta stability PyPI Anaconda Gradle plugin Maven Central GitHub Binder

Kotlin kernel for IPython/Jupyter

Kotlin (1.8.20) kernel for Jupyter.

Beta version. Tested with Jupyter Notebook 6.0.3, Jupyter Lab 1.2.6 and Jupyter Console 6.1.0 on Windows, Ubuntu Linux and macOS.

Screenshot in Jupyter

To start using Kotlin kernel for Jupyter take a look at introductory guide.

Example notebooks can be found in the samples folder

Try samples online: Binder


There are three ways to install the kernel:


If you have conda installed, just run the following command to install stable package version:

conda install -c jetbrains kotlin-jupyter-kernel (package home)

To install conda package from the dev channel:

conda install -c jetbrains-dev kotlin-jupyter-kernel (package home)

Uninstall: conda remove kotlin-jupyter-kernel


You can also install this package through pip:

Stable: pip install kotlin-jupyter-kernel (package home)

Dev: pip install -i kotlin-jupyter-kernel (package home)

Uninstall: pip uninstall kotlin-jupyter-kernel

Kotlin Notebook plugin

Just download and use the latest version of Kotlin Notebook plugin from the Marketplace. Kotlin kernel is embedded into it.

From sources

git clone --recurse-submodules
cd kotlin-jupyter
./gradlew install

Default installation path is ~/.ipython/kernels/kotlin/. To install to some other location use option -PinstallPath=, but note that Jupyter looks for the kernel specs files only in predefined places. For more detailed info see Jupyter docs.

Uninstall: ./gradlew uninstall


There could be a problem with kernel spec detection because of different python environments and installation modes. If you are using pip or conda to install the package, try running post-install fixup script:

python -m kotlin_kernel fix-kernelspec-location

This script replaces kernel specs to the "user" path where they are always detected. Don't forget to re-run this script on the kernel update.


Depending on the platform you're using, updating the Kotlin Jupyter kernel can be done in the following ways:


To update the kernel in Datalore, simply add an environment.yml to the Notebook files containing:

datalore-env-format-version: "0.2"
datalore-package-manager: "pip"
datalore-base-env: "default"
- pip:
  - kotlin-jupyter-kernel=={VERSION}

where {VERSION} should be replaced by the latest PyPi version of the Kotlin Jupyter kernel, such as Stop and restart the machine afterwards.


If you have conda installed, just run the following command to update the stable package version:

conda update -c jetbrains kotlin-jupyter-kernel

To update the conda package from the dev channel:

conda update -c jetbrains-dev kotlin-jupyter-kernel

If you want to change to a specific version of the kernel, take the install command from above and add ={VERSION} to kotlin-jupyter-kernel where {VERSION} should be replaced by the latest PyPi version of the Kotlin Jupyter kernel, such as

For example, for the stable version:

conda install -c jetbrains kotlin-jupyter-kernel={VERSION}


To update the kernel using Pip, simply run:

Stable: pip install kotlin-jupyter-kernel --upgrade

Dev: pip install -i kotlin-jupyter-kernel --upgrade

If you want to change to a specific version of the kernel, take the install command from above and add =={VERSION} to kotlin-jupyter-kernel where {VERSION} should be replaced by the latest PyPi version of the Kotlin Jupyter kernel, such as

For example, for the stable version:

pip install kotlin-jupyter-kernel=={VERSION} --ignore-installed

Kotlin Notebook

Kotlin Notebook plugin is provided with built-in kernel. To update the kernel, update plugin in IDEA (File -> Settings... -> Plugins -> Kotlin Notebook) and restart the IDE.


  • jupyter console --kernel=kotlin
  • jupyter notebook
  • jupyter lab

To start using kotlin kernel inside Jupyter Notebook or JupyterLab create a new notebook with kotlin kernel.

The default kernel will use the JDK pointed to by the environment variable KOTLIN_JUPYTER_JAVA_HOME, or JAVA_HOME if the first is not set.

JVM arguments will be set from the environment variable KOTLIN_JUPYTER_JAVA_OPTS or JAVA_OPTS if the first is not set. Additionally, arguments from KOTLIN_JUPYTER_JAVA_OPTS_EXTRA will be added. Arguments are parsed using shlex.split.

Creating Kernels

To create a kernel for a specific JDK, JVM arguments, and environment variables, you can use the add-kernel script:

python -m kotlin_kernel add-kernel [--name name] [--jdk jdk_home_dir] [--set-jvm-args] [--jvm-arg arg]* [--env KEY VALUE]* [--force]

The command uses argparse, so --help, @argfile (you will need to escape the @ in powershell), and --opt=value are all supported. --jvm-arg=arg in particular is needed when passing JVM arguments that start with -.

If jdk not specified, name is required. If name is not specified but jdk is the name will be JDK $vendor $version detected from the JDK. Regardless, the actual name of the kernel will be Kotlin ($name), and the directory will be kotlin_$name with the spaces in name replaced by underscores (so make sure it's compatible with your file system).

JVM arguments are joined with a ' ', so multiple JVM arguments in the same argument are supported. The arguments will be added to existing ones (see above section) unless --set-jvm-args is present, in which case they will be set to KOTLIN_JUPYTER_JAVA_OPTS. Note that both adding and setting work fine alongside KOTLIN_JUPYTER_JAVA_OPTS_EXTRA.

While jupyter kernel environment variable substitutions are supported in env, note that if the used environment variable doesn't exist, nothing will be replaced.

An example:

python -m kotlin_kernel add-kernel --name "JDK 15 Big 2 GPU" --jdk ~/.jdks/openjdk-15.0.2 --jvm-arg=-Xmx8G --env CUDA_VISIBLE_DEVICES 0,1

Supported functionality

REPL commands

The following REPL commands are supported:

  • :help - display help
  • :classpath - show current classpath
  • :vars - get visible variables values

Dependencies resolving

It is possible to add dynamic dependencies to the notebook using the following annotations:

  • @file:DependsOn(<coordinates>) - adds artifacts to classpath. Supports absolute and relative paths to class directories or jars, ivy and maven artifacts represented by the colon separated string
  • @file:Repository(<absolute-path>) - adds a directory for relative path resolution or ivy/maven repository. To specify Maven local, use @file:Repository("*mavenLocal").

Alternative way to do the same is using Gradle-like syntax:

    repositories {
        maven {
            url = "https://my.secret.repo/maven/"
            credentials {
                username = USER
                password = TOKEN

    dependencies {
        val ktorVersion = "2.0.3"


The same syntax can be used in integrations creating.

Note that dependencies in remote repositories are resolved via Maven resolver. Caches are stored in ~/.m2/repository folder by default. Sometimes, due to network issues or running several artifacts resolutions in parallel, caches may get corrupted. If you have some troubles with artifacts resolution, please remove caches, restart kernel and try again.

Default repositories

The following maven repositories are included by default:

Line Magics

The following line magics are supported:

  • %use - injects code for supported libraries: artifact resolution, default imports, initialization code, type renderers. Usage example: %use klaxon(5.5), lets-plot
  • %trackClasspath - logs any changes of current classpath. Useful for debugging artifact resolution failures. Usage example: %trackClasspath [on|off]
  • %trackExecution - logs pieces of code that are going to be executed. Useful for debugging of libraries support. Usage example: %trackExecution [all|generated|off]
  • %useLatestDescriptors - use latest versions of library descriptors available. By default, bundled descriptors are used. Note that default behavior is preferred: latest descriptors versions might be not supported by current version of kernel. So if you care about stability of the notebook, avoid using this line magic. Usage example: %useLatestDescriptors [on|off]
  • %output - output capturing settings. Usage example: %output --max-cell-size=1000 --no-stdout --max-time=100 --max-buffer=400
  • %logLevel - set logging level. Usage example: %logLevel [off|error|warn|info|debug]

See detailed info about line magics here.

Supported Libraries

When a library is included with %use keyword, the following functionality is added to the notebook:

  • repositories to search for library artifacts
  • artifact dependencies
  • default imports
  • library initialization code
  • renderers for special types, e.g. charts and data frames

This behavior is defined by json library descriptor. Descriptors for all supported libraries can be found in libraries repository. A library descriptor may provide a set of properties with default values that can be overridden when library is included. The major use case for library properties is to specify a particular version of library. If descriptor has only one property, it can be defined without naming:

%use krangl(0.10)

If library descriptor defines more than one property, property names should be used:

%use spark(scala=2.11.10, spark=2.4.2)

Several libraries can be included in single %use statement, separated by ,:

%use lets-plot, krangl, mysql(8.0.15)

You can also specify the source of library descriptor. By default, it's taken from the libraries repository. If you want to try descriptor from another revision, use the following syntax:

// Specify some git tag from this repository
%use lets-plot@
// Specify commit sha, with more verbose syntax
%use lets-plot@ref[24a040fe22335648885b106e2f4ddd63b4d49469]
// Specify git ref along with library arguments
%use krangl@dev(0.10)

Note that using descriptor from specific revision is better than using %useLatestDescriptors.

Other options are resolving library descriptor from a local file or from remote URL:

// Load library from file
%use mylib@file[/home/user/lib.json]
// Load library from file: kernel will guess it's a file actually
%use @/home/user/libs/lib.json
// Or use another approach: specify a directory and file name without 
// extension (it should be JSON in such case) before it
%use lib@/home/user/libs
// Load library descriptor from a remote URL
%use herlib@url[]
// If your URL responds with 200(OK), you may skip `url[]` part:
%use @
// You may omit library name for file and URL resolution:
%use @file[lib.json]

List of supported libraries:

  • biokotlin - BioKotlin aims to be a high-performance bioinformatics library that brings the power and speed of compiled programming languages to scripting and big data environments.
  • combinatoricskt - A combinatorics library for Kotlin
  • coroutines - Asynchronous programming and reactive streams support
  • dataframe - Kotlin framework for structured data processing
  • datetime - Kotlin date/time library
  • deeplearning4j - Deep learning library for the JVM
  • deeplearning4j-cuda - Deep learning library for the JVM (CUDA support)
  • default - Default imports: dataframe and Lets-Plot libraries
  • exposed - Kotlin SQL framework
  • fuel - HTTP networking library
  • gradle-enterprise-api-kotlin - A library to use the Gradle Enterprise API in Kotlin scripts or projects
  • gral - Java library for displaying plots
  • jdsp - Java library for signal processing
  • kalasim - Discrete event simulator
  • kaliningraph - Graph library with a DSL for constructing graphs and visualizing the behavior of graph algorithms
  • kandy - Kotlin plotting DSL for Lets-Plot
  • kandy-echarts - Kotlin plotting DSL for Apache ECharts
  • khttp - HTTP networking library
  • klaxon - JSON parser for Kotlin
  • kmath - Experimental Kotlin algebra-based mathematical library
  • kotlin-dl - KotlinDL library which provides Keras-like API for deep learning
  • kotlin-statistics - Idiomatic statistical operators for Kotlin
  • krangl - Kotlin DSL for data wrangling
  • kraphviz - Graphviz wrapper for JVM
  • kravis - Kotlin grammar for data visualization
  • lets-plot - ggplot-like interactive visualization for Kotlin
  • lets-plot-dataframe - A bridge between Lets-Plot and dataframe libraries
  • lets-plot-gt - Lets-Plot visualisation for GeoTools toolkit
  • lib-ext - Extended functionality for Jupyter kernel
  • londogard-nlp-toolkit - A Natural Language Processing (NLP) toolkit for Kotlin on the JVM
  • multik - Multidimensional array library for Kotlin
  • mysql - MySql JDBC Connector
  • openai - OpenAI API for Jupyter Notebooks
  • plotly - [beta] Plotly.kt jupyter integration for static plots.
  • plotly-server - [beta] Plotly.kt jupyter integration for dynamic plots.
  • rdkit - Open-Source Cheminformatics Software
  • reflection - Imports for Kotlin Reflection
  • roboquant - Algorithmic trading platform written in Kotlin
  • serialization - Kotlin multi-format reflection-less serialization
  • smile - Statistical Machine Intelligence and Learning Engine
  • spark - Kotlin API for Apache Spark: unified analytics engine for large-scale data processing
  • spark-streaming - Kotlin API for Apache Spark Streaming: scalable, high-throughput, fault-tolerant stream processing of live data streams
  • webtau - WebTau end-to-end testing across layers

Rich output

By default, the return values from REPL statements are displayed in the text form. To use richer representations, e.g. to display graphics or html, it is possible to send MIME-encoded result to the client using the MIME helper function:

fun MIME(vararg mimeToData: Pair<String, String>): MimeTypedResult 


MIME("text/html" to "<p>Some <em>HTML</em></p>", "text/plain" to "No HTML for text clients")

HTML outputs can also be rendered with HTML helper function:

fun HTML(text: String): MimeTypedResult


Rendering is a procedure of transforming of the value to the form that is appropriate for displaying in Jupyter client. Kernel supports several features that allow you to render values.


Renderers can transform a value into another value. Library can define one or several renderers. Rendering with renderers is controlled via RenderersProcessor. You can access it via notebook. Renderers are applied until at least one renderer can be applied.

DisplayResult and Renderable

If object implements DisplayResult or Renderable, it will be rendered to output JsonObject via its own corresponding method.

Text rendering

Text renderers render objects to strings. Library can define one or several text renderers. Rendering with text renderers is controlled via TextRenderersProcessor. You can access it via notebook. Text renderers are applied until at least one renderer returns non-null string for a passed argument. This kind of renderers can be easily composed with each other. I.e. text renderer for iterables can render its elements with text renderers processor recursively.

Common rendering semantics

Evaluated value is firstly transformed with RenderersProcessor. Resulting value is checked. If it's Renderable or DisplayResult, it is transformed into output JSON using toJson() method. If it's Unit, the cell won't have result at all. Otherwise, value is passed to TextRenderersProcessor. It tries to render the value to string using defined text renderers having in mind their priority. If all the renderers returned null, value is transformed to string using toString(). Resulting string is wrapped to text/plain MIME JSON.


Press TAB to get the list of suggested items for completion. In Jupyter Notebook, you don't need to press TAB, completion is requested automatically. Completion works for all globally defined symbols and for local symbols which were loaded into notebook during cells evaluation.

Error analysis

If you use Jupyter Notebook as Jupyter client, you will also see that compilation errors and warnings are underlined in red and in yellow correspondingly. This is achieved by kernel-level extension of Jupyter notebook which sends error-analysis requests to kernel and renders their results. If you hover the cursor over underlined text, you will get an error message which can help you to fix the error.


  1. Run ./gradlew installDebug. Debugger port is selected automatically. Default port is 1044, consequent ports will be used if it's in use. If you want an exact port, specify -PdebugPort=<port> Gradle option.
  2. Run jupyter notebook, open the desired notebook.
  3. Attach a remote debugger to JVM with corresponding port (debug port number will be printed in terminal on kernel startup).

Adding new libraries

Read this article if you want to support new JVM library in the kernel.


There is a site with rendered KDoc comments from the codebase. If you are a library author you may be interested in api module (see adding new libraries). There is also a lib module which contains entities available from the Notebook cells and shared-compiler module which may be used for Jupyter REPL integration into standalone application or IDEA plugin.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page