Skip to content

Jupyter Notebook#

The Jupyter ecosystems features several web applications and servers:

  • Jupyter Notebook is a web application to run an interactive computational notebooks (suffix .ipynb). You can install and start Notebook yourself locally on your machine or remote on a cluster frontend/node. To access a remotely started Jupyter Notebook a port forwarding via SSH is required. All this is covered on this page.

  • JupyterLab is an IDE as web application with more features than a Jupyter Notebooks. JupyterLab is installed and started by you. We do not cover it in this documentation.

  • JupyterHub is multi-user server. The server is typically managed by someone else. On the server you can login and start notebooks, terminals, and possible other installed extensions or kernels.

    We operate JupyterHub instances for you.

This page describes the usage of Jupyter Notebook, see JupyterHub for our JupyterHub instances.

Installing Jupyter Notebook#

To install Jupyter Notebook ensure you have:

Then install Notebook by executing:

pip install notebook

For more information, see the official installation guide.

Using remote Jupyter Notebooks#

You can run Jupyter Notebook on a cluster frontend or node and access it from your local machine through a browser by creating a port forwarding from your local machine to the corresponding remote server via SSH.

For details see Setup port forwarding to a cluster frontend or node.

The steps are:

  1. Login the the cluster frontend or start a job on the compute node you want to start Jupyter Notebook on.

  2. Obtain the fully qualified domain name (FQDN) of the machine you logged in/got a job, further on called remote server:

    hostname
# output can look like one of the following lines:
# <name>.nhr.fau.de  
# <name>.rrze.fau.de
# <name>.rrze.uni-erlangen.de

  3. Start Jupyter Notebook on the remote server, it will listen on port <remote port>: 

    jupyter notebook --no-browser --port=<remote port>

    <remote port> has to be replaced by a port number from the range of 1025 and 65535 that is currently unused on the remote system.

  4. Look for the line http://localhost:<remote port>/tree?token=<numbers and digits> and copy it.

  5. On your local machine create a port forwarding to the remote machine. This will allow accessing the remote Jupyter Notebook running on <remote server> port <remote port> through navigating your browser to http://localhost:<local port>?<numbers and digits>:

    ssh -L <local port>:localhost:<remote port> <remote server>
    • <local port> must be replaced by a port number from the range of 1025 and 65535 that is currently unused on your local system.
    • <remote server> has to be replaced by FQDN of the remote server from step 2.

  6. Open a browser on your local machine and navigate to the URL from step 4, but first replace <remote port> by <local port>. The final URL looks then like: 

    http://localhost:<local port>/tree?token=<numbers and digits>`.

New Jupyter Notebook servers do not require setting a password, as they only provide access when the correct token is specified. This is the new default.

Some useful functions and aliases to be defined/run on your local machine:

alias remote_notebook_stop='ssh username@remote_server_ip "pkill -u username jupyter"'

Be aware this will kill all Jupyter processes that you own!

start_jp_woody() {
  nohup ssh -J username@csnhr.nhr.fau.de -L $1:localhost:$1 username@woody.nhr.fau.de " 
. /etc/bash.bashrc.local; module load python/3.7-conda ; jupyter notebook --port=$1 --no-browser" ;
echo ""; echo " the notebook can be started in your browser at: https://localhost:$1/ " ; echo ""}

start_jp_meggie(){
nohup ssh -J username@csnhr.nhr.fau.de -L $1:localhost:$1 username@meggie.rrze.fau.de " 
. /etc/profile; module load python/3.7-conda ; jupyter notebook --port=$1 --no-browser" ;
echo ""; echo " the notebook can be started in your browser at: https://localhost:$1/ " ; echo ""}

Using conda/virtual environments in a Jupyter Notebook#

To use a conda/virtual environment in a Jupyter Notebook two options exists:

Option 1: Install Jupyter Notebook into your conda/virtual environment#

The Jupyter Notebook must then always be launched from within the conda/virtual environment.

The steps are:

  1. Activate your environment
  2. Install Jupyter Notebook into the environment by executing: 
    pip install notebook
  3. Start Jupyter as usual, but from inside the activated environment.

Option 2: Register your environment in Jupyter as another kernel.#

Whenever you start a Jupyter Notebook you can select the environment as kernel. For details see the official documentation.

The steps are:

  1. Registration, must only be performed once:
    1. Activate your environment.
    2. Install ipykernel package: 
      # for conda:
conda install ipykernel
# for conda, venv, etc:
pip install ipykernel
    3. Register this environment as a new kernel in Jupyter: 
      python3 -m ipykernel install --user --name=<the name of your environment>
      This registers the current environment as a Jupyter kernel under the name specified with the --name flag. An existing kernel with the same name will be over written.
  2. Usage:
    1. Start Jupyter Notebook as usual. You do not need to activate your environment first.
    2. Open your notebook.
    3. Choose the kernel of your environment. In the menu of the notebook click Kernel > Change Kernel > the name of your environment.