Integrate Workbench with Jupyter Notebook and JupyterLab on a Single Server

Workbench

These steps describe how to integrate Jupyter Notebook and Jupyterlab with Posit Workbench running on a single server.

This integration makes use of the Launcher in Workbench to spawn Jupyter Notebook and JupyterLab sessions on a single node without the use of an external resource manager.

Important

Posit Workbench supports Jupyter Lab 2.x and 3.x which are compatible with supported versions of Python, with the exception of Python 3.12.

There are known issues when installing the full dependency tree for JupyterLab versions below 4.x in Python 3.12 at this time. As such, we do not expect JupyterLab 2.x or 3.x to work on Python 3.12. Posit Workbench will support JupyterLab 4.0 in a future release.

To track progress on JupyterLab’s compatability for Python 3.12 please see:

  • https://github.com/jupyterlab/jupyterlab/issues/14507
  • https://github.com/jupyterlab/jupyterlab/issues/15332

Additional information on the supported versions is available in the Jupyter versions section.

Step 1. Install Python

Caution

The procedures below have been tested against Python version 3.11.5. Python 3.12 does not support jupyterlab <4.0, so you must keep your Python version below 3.12.

  • Use the Install Python steps to install the following on the server:

    • Python, pip

      Note

      Our recommended installation instructions for Python allow you to make multiple versions of Python available and avoid replacing existing versions of Python when updating system packages.

Step 2. Install Jupyter Notebook, JupyterLab, and Python packages

  • From the previous step, you should have the PYTHON_VERSION environment variable defined with the version of Python that you installed. If not, define this environment variable before proceeding by running the following command and replacing 3.11.5 with the version of Python that you are using:

    Terminal
    $ export PYTHON_VERSION=3.11.5

  • Install Jupyter Notebook, JupyterLab, and the notebook extensions for Workbench and Connect:

    Terminal
    $ sudo /opt/python/${PYTHON_VERSION}/bin/pip install jupyter jupyterlab==3.6.5 rsp_jupyter rsconnect_jupyter workbench_jupyterlab==1.1.315

  • Install and enable the Jupyter Notebook extensions:

    Terminal
    $ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension install --sys-prefix --py rsp_jupyter
$ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension enable --sys-prefix --py rsp_jupyter
$ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension install --sys-prefix --py rsconnect_jupyter
$ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter
$ sudo /opt/python/${PYTHON_VERSION}/bin/jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter

Step 3. Configure Launcher with Jupyter Notebook

  • Add the following lines to the Launcher Jupyter configuration file:

    /etc/rstudio/jupyter.conf
    jupyter-exe=/opt/python/3.11.5/bin/jupyter
notebooks-enabled=1
labs-enabled=1
default-session-cluster=Local
    • If you installed a version other than Python 3.11.5, then you can replace 3.11.5 in the above jupyter-exe setting with the version of Python that you installed.

Step 4. Restart Workbench and Launcher Services

  • Run the following to restart services:

    Terminal
    $ sudo rstudio-server restart
$ sudo rstudio-launcher restart

Step 5. Test Workbench with Launcher and Jupyter Notebook

  • From your browser, navigate to the Workbench interface and log in.

  • Select New Session and do the following:

    1. Give your session a name.

    2. In the Editor field, select either Jupyter Notebooks or JupyterLab as the IDE.

    3. Click Start Session.

    A screenshot of the New Session dialog on the Workbench homepage, configured to launch a new Jupyter Notebook session locally.

Now, you can use the Jupyter Notebooks or JupyterLab interfaces.

Warning

Some local Jupyter configurations may prevent the JupyterLab session from correctly launching in Workbench. For example, setting a password in the files ~/.jupyter/jupyter-server-config.json or ~/jupyter/jupyter-server-config.py, will cause the JupyterLab session to start but not load through the Workbench interface. Commenting out the configuration in question is sufficient to restore expected functionality.

(Optional) Configure multiple Python versions or environments

The Python integration steps described above result in a single Python environment that contains both core packages for Jupyter Notebooks as well as Python packages for end users.

While this is a simple approach, this setup can result in issues if end users want to use different versions of the same package or if some packages conflict with core packages for Jupyter Notebooks.

If you would like to use multiple versions of Python or different Python environments, or if you want to install Jupyter Notebook in a separate environment from Python packages for end users, then you can refer to the documentation for using multiple Python versions and environments with Jupyter.

Additional Documentation

For more information on Workbench and Jupyter Notebook, reference the Jupyter Sessions section.