Integrate Workbench with Jupyter via JupyterLab on a Single Server
These steps describe how to integrate Jupyter with Posit Workbench running on a single server.
This integration makes use of the Launcher in Workbench to spawn JupyterLab sessions on a single node without the use of an external resource manager.
Step 1. Install Python
- Use the Install Python steps to install the following on the server:
Python,
pip
NoteOur 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 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 replacing3.11.5
with the version of Python that you are using:Terminal
$ export PYTHON_VERSION=3.11.5
Perform only the steps in the section below for the version of JupyterLab that you are installing (Configuring JupyerLab 4 or Configuring JupyterLab 3).
We recommend installing JupyterLab 4 unless your use case requires JupyterLab 3.
Configuring JupyterLab 4
If you are installing JupyterLab 4, install JupyterLab, Notebook, and the Workbench extension:
Terminal
$ sudo /opt/python/${PYTHON_VERSION}/bin/pip install jupyterlab==4.1.4 notebook pwb_jupyterlab~=1.0
Continue to Step 3. Configure Launcher with Jupyter
Configuring JupyterLab 3
If you installed JupyterLab 4, do not perform the steps in this section and continue to Step 3. Configure Launcher with Jupyter
If you are installing JupyterLab 3, install Jupyter Notebook, JupyterLab, and the notebook extensions for Workbench and Connect:
Terminal
$ sudo /opt/python/${PYTHON_VERSION}/bin/pip install jupyterlab==3.6.5 rsp_jupyter rsconnect_jupyter workbench_jupyterlab==1.1
Then, install and enable the Jupyter Notebook extensions for JupyterLab 3:
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
Add the following lines to the Launcher Jupyter configuration file:
/etc/rstudio/jupyter.conf
jupyter-exe=/opt/python/3.11.5/bin/jupyter 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 abovejupyter-exe
setting with the version of Python that you installed.If you are configuring Jupyter Notebook Classic sessions, you also need to include the following:
/etc/rstudio/jupyter.conf
notebooks-enabled=1
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
From your browser, navigate to the Workbench interface and log in.
Select New Session and do the following:
-
Give your session a name.
-
In the Editor field, select either Jupyter Notebooks or JupyterLab as the IDE.
-
Click Start Session.
-
Now, you can use the Jupyter Notebook or JupyterLab interfaces.
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 Notebook, 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 Notebook.
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, reference the Jupyter Sessions section.