Jupyter configuration

Workbench

Configuration of the Jupyter feature is handled via the config file /etc/rstudio/jupyter.conf. The following table lists the various configuration options that are available to be specified in the jupyter.conf configuration file:

/etc/rstudio/jupyter.conf

Before proceeding, review the Requirements.

Config Option Description Default Value
labs-enabled Enables launching of JupyterLab sessions. Defaults to 0, but new installs place 1 in the default version of jupyter.conf. 0, 1 for new installs
notebooks-enabled Enables launching of Jupyter Notebook Classic sessions. 0 (disabled)
jupyter-exe Path to the Jupyter executable. “”
lab-command The Jupyter command to run when starting a Lab session. lab
lab-version The version of Jupyter Lab being used. If set to auto, the version is automatically detected by running the Jupyter Lab version command on the Posit Workbench node. If Jupyter is being launched via the Launcher and is not installed on the Posit Workbench node, must set this to the version in use. Using different Jupyter versions for different sessions is not supported. auto
lab-args Arguments passed to the Jupyter Lab command. This value overrides the defaults. To preserve any default arguments, you must explicitly include them in this configuration value. Modify with caution. --no-browser --allow-root --ip=0.0.0.0
notebook-command The Jupyter command to run when starting a Jupyter Notebook Classic session. notebook
notebook-version The version of Jupyter Notebook being used. If set to auto, the version is automatically detected by running the Jupyter Notebook version command. If Jupyter is being launched via the Launcher and is not installed locally, you are strongly encouraged to set this to the version in use. Running against multiple different Jupyter versions simultaneously in different Launcher clusters is not supported - they must all be running the same version, or proxying issues will occur. auto
notebook-args Arguments passed to the Jupyter Notebook command. This value overrides the defaults. To preserve any default arguments, you must explicitly include them in this configuration value. Modify with caution. --no-browser --allow-root --ip=0.0.0.0
session-clusters Deprecated in favor of launcher-sessions-clusters. List of available Job Launcher clusters for launching Jupyter sessions. launcher-sessions-clusters in rserver.conf
default-session-cluster Deprecated in favor of launcher-default-cluster. The default Job Launcher cluster to use when launching a Jupyter session. launcher-default-cluster in rserver.conf
default-session-container-image The default container image to use when launching a containerized Jupyter session.
session-container-images Comma-delimited list of images that may be used for running Jupyter sessions.
jupyter-session-path Path to the Jupyter Session launcher executable/script. It is recommended that you do not change this unless you know what you’re doing, and you need to point to a different script. /usr/lib/rstudio-server/bin/jupyter-session-run
session-no-profile Enables/disables running of bash profile scripts when starting Jupyter sessions. 0 (run profile scripts)
session-shutdown-minutes The amount of idle time to wait in minutes before a Jupyter session is shut down after its kernels have been culled. To disable automatic shutdown, set the value to 0. Sets the following Jupyter argument: --ServerApp.shutdown_no_activity_timeout=<60 * session-shutdown-minutes value>
See Session timeouts and cleanup		 5
session-cull-minutes The amount of idle time to wait in minutes before a Jupyter session’s kernels are automatically “culled” (shut down). To disable culling, set the value to 0. Enabling this sets the following Jupyter arguments: --MappingKernelManager.cull_interval=60 --MappingKernelManager.cull_idle_timeout=<60 * session-cull-minutes value>
See Session timeouts and cleanup		 120
session-cull-connected Culls kernels with one or more front end clients/code cells. Only applies if session-cull-minutes > 0. Sets the --MappingKernelManager.cull_connected Jupyter setting.
See Session timeouts and cleanup		 1 (true)

For example, your jupyter.conf file might look like the following:

# /etc/rstudio/jupyter.conf
jupyter-exe=/usr/bin/jupyter
labs-enabled=1
session-cull-minutes=0
default-session-cluster=Kubernetes
default-session-container-image=rstudio:jupyter-session

Jupyter versions

Due to differences between Jupyter versions, Posit Workbench needs to know the versions of JupyterLab and Jupyter Notebook in use when running Jupyter Notebook Classic. These versions can be automatically detected at startup, since Workbench runs the jupyter command to determine them. You can also specify them via the lab-version and notebook-version settings in /etc/rstudio/jupyter.conf. The default value of auto enables automatic detection.

If you are running Jupyter in a remote cluster like Kubernetes, you will need to manually specify the version of Jupyter if it is not locally installed or is not running the same version as the remote cluster.

To run multiple versions of Jupyter across different clusters, follow the instructions at Varied installation locations.

You should specify a full Jupyter 3-part version number like so:

# /etc/rstudio/jupyter.conf
lab-version=4.2.5

Varied installation locations

In some cases, the path to jupyter might be different depending on where the JupyterLab or Jupyter Notebook session is running. The path to jupyter might vary from container to container. By specifying a WORKBENCH_JUPYTER_PATH environment variable in your container build, you can ensure that the desired Jupyter installation will be executed by Workbench. The WORKBENCH_JUPYTER_PATH variable can also be set in the launcher-env file as described in the Launcher environment section. Workbench will resolve which jupyter executable should be used with the following priority:

  1. The value of the WORKBENCH_JUPYTER_PATH environment variable, if set.
  2. The value of exe as defined in jupyter.conf.
  3. A jupyter installation that is on the PATH.

If there is no jupyter at any of those locations, JupyterLab and Jupyter Notebook sessions will fail to start.

Note

Please note that jupyter must still be installed at the location configured in jupyter.conf on the Workbench host.

Launcher configuration

When creating containerized Jupyter sessions via the Job Launcher, you will need to specify mount points as appropriate to mount the users’ home drives and any other desired paths. In order for sessions to run properly within containers, it is required to mount the home directories into the containers.

For more information, see Launcher mounts.

Note

If you are using NFSv3 for the shared storage for user home directories, you will need to set the local_lock=all NFS setting in /etc/fstab in order for Jupyter sessions to work properly. Failure to do this will cause Jupyter sessions to hang. For this reason, we strongly recommend the use of NFSv4 for Jupyter sessions. See the NFS documentation for information on NFS settings.

Note

Only a user’s home folder is visible within Jupyter sessions. To access other folders, create symbolic links to them within the home folder.

Container configuration

When running Jupyter sessions in containers, such as by using the Kubernetes Job Launcher plugin, you will need to ensure that the image(s) used to launch Jupyter sessions contain, at minimum, the following:

  1. Python 3.9+
  2. JupyterLab 4.x and/or Jupyter Notebook 6.x or 7.x
  3. Workbench session binaries

For containers within Kubernetes, we recommend using the rstudio/workbench-session Docker image as a base for any Jupyter session images you create. This will allow you to use one base image to provide Jupyter itself and a default version of Python, which you can extend if necessary to add or modify Jupyter and Python versions if desired. These images are available on Docker Hub.

When using the rstudio/workbench-session image on Kubernetes, the session init container should be enabled to ensure that Workbench session components are copied to the session container at runtime:

/etc/rstudio/rserver.conf
launcher-sessions-auto-update=1

See the Session init container section for more information.

When using a container-based job system other than Kubernetes, we recommend using the rstudio/r-session-complete Docker image. This image includes the Workbench session components in the image directly. This image is available on Docker Hub.

Session timeouts and cleanup

JupyterLab has a built-in session manager that can be configured to shut down idle sessions and cull Python kernels in order to free up resources. Posit Workbench exposes some of its settings in the jupyter.conf file, allowing you to configure how long sessions should be allowed to idle before they are automatically shut down.

From the table above these are:

/etc/rstudio/jupyter.conf
# cull kernels after 55 minutes, then shutdown 5 minutes later

session-shutdown-minutes=60

session-cull-minutes=55
session-cull-connected=1

“Cull” refers to the shutting down of idle kernels, while “shutdown” refers to the shutting down of the entire lab session. When a session is shut down, all resources associated with that session are freed up. When a kernel is culled, the session remains active but the kernel stops, and must be restarted by the user in order to run code.

It is important to note that these settings only apply to sessions that are not active in a browser, because the browser keeps the session active with periodic queries to the server. This behavior is part of JupyterLab and not something that Workbench controls. Users must exit their browser tab first, then JupyterLab’s session and kernel managers will be able to cull kernels and terminate sessions.

Terminals do not hold the session active. If the user runs a long terminal-based job and then closes their browser, the session shutdown setting can shut down the session anyway. Similarly, terminals are not kernels and are not subject to culling.

Adding Python environments to Jupyter

You can add new Python virtual environments or conda environments to Jupyter as Python Kernels that users can select, allowing them to have flexibility in the Python versions they can use.

The following steps show how to add a new Python virtualenv as a Kernel to Jupyter:

  1. Create the virtualenv or conda environment
  2. Add the environment as an iPython kernel
  3. Verify the kernel is available in Jupyter
# first, create the virtual env in a directory accessible by all users
cd /opt/python-kernels

# then make the virtualenv
virtualenv myenv

# alternatively, you can make a conda environment
# conda create -n myenv

# then, add the virtualenv to the Kernels list globally for all users
sudo ipython kernel install --name "myenv" --display-name "My Python Environment"

# finally, verify that the kernel is registered with Jupyter
sudo jupyter kernelspec list

Once the Kernel is listed in the output of the jupyter kernelspec list command, it will be available for use in both JupyterLab and Jupyter Notebooks.

To remove the kernel, simply run the following command:

sudo jupyter kernelspec remove "myenv"

For more information, see the IPython docs.

Installing the Posit Workbench JupyterLab extension

Workbench JupyterLab Sessions should be configured to run with the Posit Workbench JupyterLab extension. The extension provides JupyterLab sessions with a Workbench home button and allows users to access remote web servers they are developing in their JupyterLab extensions through their browsers.

If a user launches a JupyterLab Session without the extension installed, Workbench will attempt to install the extension while launching the session. In most configurations, the user will not have write access to the Python environment, and the extension will only be installed for that individual user. To provide the best user experience, admins should pre-install the extension before users run JupyterLab sessions. If you are going to rely on Workbench to install the extension, it must be able to download from www.pypi.org.

You can install the JupyterLab extension using pip within the same Python environment that JupyterLab is installed in. Additionally, you must install the extension on the node that hosts the user’s sessions (e.g., the Docker image used by a Pod in a Kubernetes cluster). When configuring JupyterLab 4 environments, install the extension pwb_jupyterlab.

ImportantJupyterLab 3 is deprecated

If you previously had JupyterLab 3 configured, you need to pip uninstall workbench_jupyterlab

JupyterLab 3 reached its end of maintenance date on May 15, 2024. Given the JupyterLab council is no longer maintaining this older version, Workbench now requires JupyterLab 4.

Installing for JupyterLab 4

To install the extension in a JupyterLab 4 environment, run the following command as a user with write permissions to the Python directory (you may need to include sudo):

    pip install pwb_jupyterlab~=1.1

To read more about the JupyterLab 4 extension and check the latest version number, visit https://pypi.org/project/pwb-jupyterlab/.

Note

If the extension hasn’t been installed when the user launches a session, they can install it themselves using the same pip command. However, the install will not fully complete until they launch their next JupyterLab session. When the extension is installed within an active JupyterLab session, only its front-end components are installed for that session, and server proxying will not work properly.

Installing additional JupyterLab extensions

Administrators can globally install JupyterLab extensions for all users using pip install.

For example, to install the jupyterlab-kernelspy extension using pip:

pip install jupyterlab-kernelspy
Note

You will need to install the desired extensions on all Launcher nodes that are running JupyterLab sessions. For containerized sessions, the extension must be installed in the container image(s) that are used.

There is no need to explicitly enable or disable the extension. Once installed, active sessions can see the extension after refreshing the browser. Other extensions can be found on Pypi.org.

In previous versions of JupyterLab, you needed to install packages from source and build them with nodejs. This flow is still supported, but installing prebuilt extensions via pip is much simpler. For more information, see the JupyterLab extension docs.

Back to top