Skip to main content

Run Jupyter on Orchestra 2

Project description

PyPI version PyPI pyversions PyPI license

Jupyter-O2 is a command-line tool that remotely runs Jupyter on Orchestra 2 (O2), an HPC cluster managed by the HMS Research Computing group.


First, follow the O2 wiki’s procedure to set up Jupyter for your account on O2. (If you have already installed Jupyter on O2, you can skip this step.)

Next, on your local machine:

Install Jupyter-O2.

pip install jupyter-o2

Then, generate the config file.

jupyter-o2 --generate-config

Follow the printed path to jupyter-o2.cfg and edit according to its instructions, particularly the DEFAULT_USER and INIT_JUPYTER_COMMANDS fields. You may copy this file to any of the locations listed by jupyter-o2 --paths if you wish.

Make sure you have X11 forwarding active (install XQuartz if on a Mac).

For more info on setting up Jupyter and troubleshooting Jupyter-O2, see the jupyter-o2 tips.

Requirements and compatibility

  • python 3.6+
  • pexpect 4.5+
  • POSIX: Jupyter-O2 requires a POSIX environment such as macOS or Linux. If you have a Windows machine, you can try using WSL2


Jupyter-O2 should be run locally using the following command format:

jupyter-o2 [subcommand]

Examples: jupyter-o2 notebook or jupyter-o2 lab (try JupyterLab!)

This will automate the “Opening a Notebook” procedure on the O2 wiki.

Note that if Jupyter is installed on your machine, Jupyter-O2 can also be run as a Jupyter subcommand:

jupyter o2 lab

For info on the Jupyter-O2 command-line options, use jupyter-o2 --help.

Two-factor authentication

Jupyter-O2 detects the Duo two-factor authentication prompt and requests a Duo push by default (code 1). To send a pre-generated code, use the argument --2fa-code <code>, replacing <code> with your code.

Experimental: use --2fa-code interact to interactively respond to the Duo prompt. This allows you to request a phone or text push and enter the code you receive.

Changelog for Jupyter-O2

1.1.0 - 2021-10-25

Jupyter-O2 detects and responds to Duo two-factor authentication prompts automatically, requesting a Duo push by default. This means that the arguments --2fa --2fa-code 1 are no longer required to use two-factor authentication; --2fa now has no effect.


  • Automatic detection and handling of 2FA prompts #10
  • More error messages in case of job submission errors #11
  • Interactive mode for responding to 2FA prompt #2

1.0.6 - 2021-06-17


  • Better error message if two-factor authentication fails
  • Warning if two-factor authentication is set incorrectly for the computer’s network location

1.0.5 - 2021-06-06


  • This version removes compatibility with Python 2.7, which has not been supported since version 1.0.2.


  • Warning message for a common error if two-factor authentication is not used


  • Fixed moving to a new jupyter port if the original port was occupied


  • Packaging system now supports PEP 517
  • Raised minimum dnspython version to 2.0

1.0.4 - 2021-02-02


  • Option to change SLURM partition


  • #3 Improved handling of hostname decode error

1.0.2 - 2020-08-24


  • #6 Jupyter-O2 now requires only a single ssh session. The second ssh session is now disabled by default and can be re-enabled in the config file.

1.0.1 - 2020-07-14


  • #4 Improved README


  • #3 Made hostname decode error more readable
  • #5 Disabled timeout when starting interactive session

1.0.0 - 2019-05-30


  • #3 Improve exception handling
  • Fix handling of alternate ports

0.2.9 - 2018-12-04


  • #1 Initial implementation of Duo 2FA handler to address new O2 login procedures

For information about older versions, see their release notes.

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-o2, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size jupyter_o2-1.1.0-py2.py3-none-any.whl (22.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size jupyter-o2-1.1.0.tar.gz (28.2 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 Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page