Skip to main content

Extension for Jupyter notebooks to connect to openBIS and download/upload datasets, inluding the notebook itself

Project description



The jupyter-openbis-extension needs at least Python 3.3 in order to run. The Jupyter notebook server starts this extension during startup and must therefore run under the same Python version. The kernel can be anything (Python 2.7, Julia, R, Perl...)

This extension has been successfully tested with Safari 12.0.3, Chrome 72.0 and Firefox 66.0. There is a known incompatibility before Firefox 61.0b13.

Development with Vagrant

If you want to use a predefined development environment, follow these steps:

  1. Install latest version of VirtualBox (

  2. Install latest version of Vagrant (

  3. vagrant plugin install vagrant-vbguest vagrant-notify-forwarder vagrant-disksize

  4. cd vagrant

  5. vagrant up

After the setup is complete, you'll have

Install the extension

If you haven't done yet: download the latest jupyter-openbis-extension from pip. It will automatically install the various dependencies, e.g. Pandas and NumPy.

pip install --upgrade jupyter-openbis-extension

or, if you would like to develop:

$ git clone
$ cd jupyter-openbis-extension
$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install -e .
(venv) $ jupyter serverextension enable --py jupyter-openbis-extension
(venv) $ jupyter nbextension install --py jupyter-openbis-extension --user --symlink
(venv) $ jupyter nbextension enable jupyter-openbis-extension --user --py

Register the Jupyter server extension which will communicate both with openBIS and the notebook:

jupyter serverextension enable --py jupyter-openbis-extension

Register the notebook extension, the client side of the Jupyter notebook, which will communicate with the server extension via AJAX calls:

 jupyter nbextension install --py jupyter-openbis-extension --user

If you are developing, you should consider creating a link to the JavaScript source instead:

 jupyter nbextension install --py jupyter-openbis-extension --user --symlink

Finally, activate the notebook extension.

jupyter nbextension enable jupyter-openbis-extension --user --py

Create a configuration file: ~/.jupyter/openbis-connections.yaml It should contain connection information to your server(s), for example:

    - name                : TEST local openBIS instance
      url                 : https://localhost:8443
      verify_certificates : false
      username            : username
      password            : password
    - name                : PRODUCTION openBIS instance
      url                 :
      verify_certificates : true
      username            : username
      password            : password

Note 1: You do not need the usernames or passwords anymore. With the current version, you are able to enter username and password directly from within a Jupyter notebook.

Note 2: You can place this file in any of these directories (on Mac OS X):

/Users/your_username/.pyenv/versions/3.6.0/etc/jupyter  # or wherever your jupyter installation is located

These directories are produced by Jupyters' nb_server_app.config_file_paths method.

Launching Jupyter notebook

Now you are ready to launch jupyter notebook!

$ jupyter notebook

Observe the terminal. It should tell you which server(s) have been successfully connected (and which not):

$ jupyter notebook
Registered: https://localhost:8443
Cannot establish connection to: https://localhost:8443
Successfully connected to:

Congratulations! You can retry non-successful connections later, directly from the GUI.

Uninstall Jupyter extension

jupyter serverextension disable --py jupyter-openbis-extension
jupyter nbextension disable --py jupyter-openbis-extension --user
jupyter nbextension uninstall --py jupyter-openbis-extension --user

This should remove the registrations in ~/.jupyter/jupyter_notebook_config.json and ~/.jupyter/nbconfig/notebook.json. The symbolic link in ~/Library/Jupyter/nbextension/ (Mac OS X) should have been removed too. If not, you can remove it manually.

Manual installation (if above should fail)

Install the Python module(s)

  • clone the project:
git clone
  • cd into the extension cd jupyter-openbis-extension
  • install the python module normally: pip install .
  • or, for development, install just a symbolic link: pip install -e .
  • this extension needs Jupyter and pyBIS 1.7.2 in order to run, so it will load / upgrade it if not yet present
  • the jupyter-openbis-extension needs at least Python 3.3 in order to run. Therefore, your Jupyter notebook server (but not the kernel!) needs to run under at least Python 3.3 too.

Register the Jupyter Notebook Server Extension (server-side, as the name suggests)

  • in the terminal, enter the following:

jupyter serverextension enable --py jupyter-openbis-extension

  • OR (1) register it manually:
  • open the file ~/.jupyter/
  • add the following:
c.NotebookApp.server_extensions = [
  • OR (2) register it in ~/.jupyter/jupyter_notebook_config.json manually, if the automatic registration fails for some reasons:
  "NotebookApp": {
    "nbserver_extensions": {
      "jupyter-openbis-extension.server": true

Register the Jupyter Notebook Extension (client-side)

Inside the folder ~/Library/Jupyter/nbextension/ (Mac OS X) create a symbolic link to the folder that contains the Java Script:

ln -s /path/to/jupyter-openbis-extension/nbextension/dialog.js jupyter-openbis-extension

In the file ~/.jupyter/nbconfig/notebook.json the JavaScript gets activated like this:

  "load_extensions": {
    "jupyter-openbis-extension/dialog": true

Check that the nbextension has been installed and activated:

$ jupyter nbextension list
Known nbextensions:
  config dir: /Users/your-username/.jupyter/nbconfig
    notebook section
      jupyter-openbis-extension/dialog  enabled 
      - Validating: OK

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jupyter-openbis-extension, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size jupyter-openbis-extension-0.1.0.tar.gz (24.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page