Configure Thebe

You control Thebe’s behavior with a configuration block that is placed somewhere in a page’s HTML. The block has the following structure:

<script type="text/x-thebe-config">
       a: collection
       of: key
       val: pairs

For example, the following configuration tells Thebe to use a BinderHub for its sessions, as well as the repository to use with Binder:

<script type="text/x-thebe-config">
    requestKernel: true,
    binderOptions: {
        repo: "binder-examples/requirements",
        ref: "master",

When Thebe is launched on a page, this configuration is used to control its behavior.

See the sections below for things that you can control with Thebe configuration.

Configure the kernel that will be launched

To configure the kernel that Thebe requests when it launches, use the following section in the Thebe configuration:

kernelOptions: {
  kernelName: "python3",

When Thebe is launched, it will request a kernel of this name for the page. Note that currently there can be only one kernel per page.


You must ensure that the value of kernelName exists in the environment that Thebe tries to launch. Some short-hands for certain languages (like python) may also work.

Configure the working directory of the launched kernel

In addition to choosing the kernel, you may also choose the path where the kernel is launched. This will be relative to the root of the launched Jupyter server (e.g., if using a BinderHub, this will be relative to the root of the repository).

To configure the path of the working directory, use the following configuration:

kernelOptions: {
  kernelName: "python3",
  path: "path/to/directory"

Customize CodeMirror

CodeMirror is the tool used to convert your code cells into editable cells. It has a number of configuration options, such as theming and syntax highlighting. You can edit all of these attributes in a cell with the following thebe configuration:

// Additional options to pass to CodeMirror instances
codeMirrorConfig: {},

You can use any of the available CodeMirror configurations. For example, the following configuration changes the CodeMirror theme:

codeMirrorConfig: {
    theme: "abcdef"

The below code cell demonstrates this theme:

%matplotlib inline
import numpy as np
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.scatter(*np.random.randn(2, 100), c=np.random.randn(100))
ax.set(title="Wow, an interactive plot!")

The above code should be styled according to the CodeMirror abcdef theme.

Mark a code cell as read-only

If you would like a code cell to be runnable by Thebe, but not editable by the user, you may mark it as “read-only” with the following syntax:

<pre data-executable data-readonly>print("I cannot be modified")</pre>

Users will not be able to modify the code once Thebe is activated, though they can still press the “run” button to see the outputs.

To set all cells as read-only by default, use the following thebe configuration:

codeMirrorConfig: {
    readOnly: true

This uses codeMirror to mark all cells as read-only. If you are using this setting and would like to manually mark individual cells as editable, you can override the codeMirror configuration for a cell using data-readonly="false". For example:

<pre data-executable data-readonly="false">print("I still can be modified")</pre>
<pre data-executable>print("Due to codeMirrorConfig, I cannot be modified")</pre>