Kotlin Kernel for Jupyter notebooks

The Kotlin Kernel for Jupyter notebooks is a powerful tool that allows you to write and run Kotlin 1.9.23 code within the Jupyter Notebook environment. This Kernel essentially acts as a bridge between Jupyter Notebook and the Kotlin compiler.

The Kotlin Kernel for notebooks supports running code cells to immediately see outputs, basic code completion, error analysis, and other interactive coding features, enhancing the interactive experience provided by the Kotlin REPL.

With the Kotlin Kernel for notebooks, you gain access to a range of features like:

• Accessing APIs within cells and using APIs for handling outputs.
• Retrieving information from previously executed code snippets, allowing quick project exploration.
• Importing various libraries with a single line of code or even integrating new libraries into your project.

You can leverage Kotlin Kernel's benefits in IntelliJ IDEA through the Kotlin Notebook plugin, in your Jupyter Notebook, or in Datalore.

Contents

Get started

Start using the Kotlin Kernel for Jupyter notebooks:

• See the introductory notebook guide.
• Check notebook samples.
• Try the sample notebooks online:
• Explore the Kotlin Notebook docs to learn about features, use cases, and tutorials.

Versions and support

> Note: The Kotlin Kernel for Jupyter notebooks is in Beta.

Kotlin version support

The latest version of the Kotlin Kernel for notebooks uses the Kotlin compiler of version 1.9.23.

Jupyter environments

We tested the Kotlin Kernel for notebooks with the following clients:

Operating systems

We tested the Kotlin Kernel for notebooks with all the mentioned clients on the following operating systems:

• Windows
• Ubuntu Linux
• macOS

Install the Kotlin Kernel in various clients

You can create, open, and work with Kotlin notebooks on various clients:

• Kotlin Notebook in IntelliJ IDEA
• Datalore
• Jupyter Notebook and JupyterLab

Our Kotlin Kernel is fully integrated into Kotlin Notebook, which you can use directly within IntelliJ IDEA by installing the Kotlin Notebook plugin.

In Datalore, Kotlin is supported natively, with the Kotlin Kernel already bundled for an out-of-the-box experience.

For other Jupyter clients, you'll need to install the Kotlin Kernel separately using conda, pip, or sources.

Install the Kotlin Notebook plugin

If you use IntelliJ IDEA, you need to install the Kotlin Notebook plugin that contains the Kotlin Kernel for Jupyter notebooks.

Install the Kotlin Notebook plugin by downloading its latest version from the JetBrains Marketplace.

Alternatively, access the Kotlin Notebook plugin from Settings | Plugins | Marketplace within IntelliJ IDEA.

> Note: For a quick introduction to Kotlin Notebook, see this blog post.

Install with Conda

If you use Jupyter Notebook and Conda, run this Conda command to install the stable version package of the Kotlin Kernel for Jupyter notebooks:

conda install -c jetbrains kotlin-jupyter-kernel

Alternatively, run this Conda command to install the package from the developers channel:

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

To uninstall the Kotlin Kernel for Jupyter notebooks, run this Conda command:

conda remove kotlin-jupyter-kernel

Install with Pip

If you use Jupyter Notebook and Pip, run this Pip command to install the stable version package of the Kotlin Kernel for Jupyter notebooks:

pip install kotlin-jupyter-kernel

Alternatively, run this Pip command to install the package from the developers channel:

pip install -i https://test.pypi.org/simple/ kotlin-jupyter-kernel

To uninstall the Kotlin Kernel for Jupyter notebooks, run this Pip command:

pip uninstall kotlin-jupyter-kernel

Install from sources

If you use either IntelliJ IDEA or Jupyter Notebook, you can install the Kotlin Kernel for Jupyter notebooks from sources.

Clone this repository and run the following Gradle command in the root folder:

./gradlew install

The default installation path is ~/.ipython/kernels/kotlin/. You can also install the package in another location using the -PinstallPath= option. However, Jupyter only looks for the kernel specification files in predefined places. For more details, see Jupyter docs.

To uninstall the Kotlin Kernel for Jupyter notebooks from sources, run this Gradle command:

./gradlew uninstall

Troubleshoot your installation

When installing the Kotlin Kernel for Jupyter notebooks, issues can occur while detecting the kernel specification file. These issues occur due to different Python environments and installation modes.

If you are using Pip or Conda to install the package, run this post-install fixup script:

python -m kotlin_kernel fix-kernelspec-location

This script replaces the kernel specification files with the detected user path.

> Note: Don't forget to re-run this script when updating the Kotlin Kernel for notebooks.

Update the Kotlin Kernel for notebooks

See how to update the Kotlin Kernel for Jupyter notebooks using the Kotlin Notebook plugin, Conda, Pip, and Datalore.

Update the Kotlin Notebook plugin

If you use the Kotlin Notebook plugin, update it to the latest version in Settings | Plugins | Installed within IntelliJ IDEA.

Alternatively, you can download and install the latest plugin version from the JetBrains Marketplace.

Update with Conda

If you use Jupyter Notebook and Conda, run this Conda command to update the stable version package:

conda update -c jetbrains kotlin-jupyter-kernel

Alternatively, run this Conda command to update the package from the developers channel:

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

To change to a specific Kotlin Kernel version, add the ={VERSION} parameter to the kotlin-jupyter-kernel command. In this command, replace the {VERSION} parameter with the desired PyPi version of the Kotlin Jupyter Kernel (for example, 0.12.0-167).

You can specify the version in both commands the one from the stable package and the one from the developers channel package. For example, for the stable package:

conda install -c jetbrains kotlin-jupyter-kernel={0.12.0-167}

Update with Pip

If you use Jupyter Notebook and Pip, run this Pip command to update the stable version package:

pip install kotlin-jupyter-kernel --upgrade

Alternatively, run this Conda command to update the package from the developers channel:

pip install -i https://test.pypi.org/simple/ kotlin-jupyter-kernel --upgrade

To change to a specific Kotlin Kernel version, add the ={VERSION} parameter to the kotlin-jupyter-kernel command. In this command, replace the {VERSION} parameter with the desired PyPi version of the Kotlin Jupyter Kernel (for example, 0.12.0-167).

You can specify the version in both commands the one from the stable package and the one from the developers channel package. For example, for the stable package:

pip install kotlin-jupyter-kernel=={0.12.0-167} --ignore-installed

Update in Datalore

To update the Kotlin Kernel for notebooks in Datalore:

1. Add an environment.yml file to the Notebook files containing the following snippet:

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

2. Replace the {VERSION} parameter for the latest PyPi version of the Kotlin Jupyter Kernel (for example, 0.12.0-167).

3. Stop and restart the machine in Datalore.

Use the Kotlin Kernel for notebooks

See how to use the Kotlin Kernel for Jupyter notebooks with the Kotlin Notebook plugin, Jupyter clients, and Datalore.

Use the Kotlin Notebook

After installing the Kotlin Notebook plugin in IntelliJ IDEA, create a new notebook by selecting File | New | Kotlin Notebook, or right-click on a folder and select New | Kotlin Notebook.

Now you're good to go!

Use other Jupyter clients

You can use our Kotlin Kernel through JupyterLab, Jupyter Notebook, and Jupyter Console clients:

1. Run one of the following commands in the console:

• In JupyterLab:

  jupyter lab

• In Jupyter Notebook:

  jupyter notebook

• In Jupyter Console:

  jupyter console --kernel=kotlin

2. Create a new notebook and set kotlin as kernel. This step applies to Jupyter Notebook or JupyterLab, and it's not required for Jupyter Console.

The default kernel uses the JDK that the environment points in the KOTLIN_JUPYTER_JAVA_HOME variable. In case the KOTLIN_JUPYTER_JAVA_HOME variable is not set, the kernel also uses the JDK from the JAVA_HOME variable.

The kernel uses the arguments that the environment points in the KOTLIN_JUPYTER_JAVA_OPTS variable. In case the KOTLIN_JUPYTER_JAVA_OPTS variable is not set, the kernel also uses the JVM arguments from the JAVA_OPTS variable.

Additionally, the kernel uses arguments that the environment points in the KOTLIN_JUPYTER_JAVA_OPTS_EXTRA variable. The arguments are parsed using the Python shlex.split() function.

Use Datalore

To create a Kotlin notebook in Datalore, click on New notebook and select Kotlin as kernel.

Create custom kernels

You can create a custom Kotlin Kernel for Jupyter Notebook. This allows you to tailor the kernel's environment to your specific requirements, such as using a particular JDK, setting JVM arguments, or defining environment variables.

To create a custom Kotlin Kernel for Jupyter Notebook, use the add-kernel command from the installed kotlin_kernel python package:

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

In the add-kernel script, the name argument is required if the jdk argument is not specified. Alternatively, if the jdk argument is specified, but the name argument is not, then the name is taken from the JDK $vendor $version argument, which is detected from the JDK.

Regardless of how the name is determined, the format of the kernel name is Kotlin ($name), and the format of the directory name is kotlin_$name. The directory name includes spaces in name, replaced by underscores. Ensure this format is compatible with your file system.

JVM arguments are joined with a space (' '), supporting multiple arguments within the same entry. The new arguments are added to existing ones, unless the --set-jvm-args flag is used. In this case, JVM arguments are set to the KOTLIN_JUPYTER_JAVA_OPTS variable. Both adding and setting arguments work alongside the KOTLIN_JUPYTER_JAVA_OPTS_EXTRA variable.

While Jupyter Kernel environment variable substitutions are supported in the env argument, no replacement occurs if the used environment variable doesn't exist.

The add-kernel script utilizes the argparse Python library, supporting the --help, @argfile (you don't need the @ symbol in PowerShell), and --opt=value arguments. The --jvm-arg=arg argument is required when passing JVM arguments that start with the - symbol.

Here's an example of an add-kernel script to create a custom Kotlin Kernel for Jupyter Notebook:

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

Features

Explore the sections below to learn about the features of the Kotlin Kernel for Jupyter notebooks. You can leverage these features using Kotlin Notebook in IntelliJ IDEA, Datalore, or other Jupyter Notebook clients.

The features of the Kotlin Kernel for Jupyter notebooks include:

• REPL commands
• Dependencies resolving
• Default repositories
• Line magics
• Supported libraries
• Rich output
• Rendering
• Autocompletion
• Error analysis

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

	dependencies {
		val ktorVersion = "2.0.3"

		implementation("my.secret:artifact:1.0-beta")
		implementation("io.ktor:ktor-client-core:$ktorVersion")
		implementation("io.ktor:ktor-client-apache:$ktorVersion")
	}
}

%use dataframe(0.10)

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

%use kandy, dataframe, mysql(8.0.15)

// Uses a specific version from the default repository
%use lets-plot@0.8.2.5

// Uses a specific commit of the library
%use lets-plot@ref[24a040fe22335648885b106e2f4ddd63b4d49469]

// Uses a specific version of the library from a custom repository along with library arguments
%use dataframe@dev(0.10)

// Loads the library from a file
%use mylib@file[/home/user/lib.json]

// Loads the library from a file, and the Kernel detects it's a file
%use @/home/user/libs/lib.json

// Specifies a directory and a file name without extension (the extension file should be JSON) 
%use lib@/home/user/libs

// Loads the library descriptor from a remote URL
%use herlib@url[https://site.com/lib.json]

// Loads the library descriptor from a remote URL. The `url[]` part can be omitted if the URL responds with 200(OK)
%use @https://site.com/lib.json

// Loads the library dependencies from a specified JSON file. The library name and URL resolution can be omitted
%use @file[lib.json]

fun MIME(vararg mimeToData: Pair): MimeTypedResult 

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

fun HTML(text: String): MimeTypedResult

HTML("<p>This is an example of <strong>HTML</strong> content rendered using the HTML helper function.</p>")

Debug your Kotlin notebook client

1. Run the ./gradlew installDebug Gradle command. The debugger port is selected automatically. The default port is 1044, and if it's unavailable, the consequent ports are used. If you want an exact port, specify the -PdebugPort= Gradle option.
2. Run the corresponding command to open the desired notebook client.
3. Attach a remote debugger to the JVM with the corresponding port (the debug port number is printed in the terminal when the kernel starts).

Integrate new libraries

Read this article if you want to integrate new JVM libraries in the Kotlin Kernel for Jupyter notebooks.

Documentation

To learn more, explore the available documentation:

• Docs site with rendered KDoc comments from the codebase.
• Docs about integrating new libraries. If you are a library author, you may be interested in the api module in our project. There is also a lib module that contains entities available from the Notebook cells, and a shared-compiler module for Jupyter REPL integration into a standalone application or IDEA plugin.
• Explore the Kotlin Notebook docs to learn about features, use cases, and tutorials.

Contribute

We welcome contributions to further enhance our project! If you come across any issues or have feature requests, please don't hesitate to file an issue.

For issues specifically related to the Kotlin Notebook plugin, utilize this tracker.

Pull requests are highly appreciated! When submitting a pull request, ensure it corresponds to an existing issue.

If you are planning a substantial change, we recommend discussing it with a project maintainer. You can reach out to me through email, Kotlin Slack, or Telegram.

We look forward to your contributions!