# Jupyter Notebook

[ExCl](https://docs.excl.ornl.gov) → [User Documentation](https://docs.excl.ornl.gov/~/revisions/tgK4OWTltCS04RkJelGW/readme) → [Jupyter Quick Start](https://docs.excl.ornl.gov/~/revisions/tgK4OWTltCS04RkJelGW/quick-start-guides/jupyter-quick-start)

## Installing Jupyter

Since there are many ways to install Jupyter using various python management tools, I will not reproduce the documentation here. The official documentation for installing Jupyter can be found at [Project Jupyter | Installing Jupyter](https://jupyter.org/install). However, I will highlight the methods of using [Jupyter with UV](https://docs.excl.ornl.gov/quick-start-guides/jupyter-quick-start#jupyter-with-uv), running [Jupyter Notebooks in VS Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks), and the alternative to Jupyter notebooks, [Marimo | ExCL User Docs](https://docs.excl.ornl.gov/quick-start-guides/marimo). These methods are all the methods that I typically use when working with python notebooks.

### Jupyter with UV

See the UV documentation, [Using uv with Jupyter | uv](https://docs.astral.sh/uv/guides/integration/jupyter/). This documentation is well written and covers:

* [Using Jupyter within a project](https://docs.astral.sh/uv/guides/integration/jupyter/#using-jupyter-within-a-project)
  * [Creating a kernel](https://docs.astral.sh/uv/guides/integration/jupyter/#creating-a-kernel)
  * [Installing packages without a kernel](https://docs.astral.sh/uv/guides/integration/jupyter/#installing-packages-without-a-kernel)
* [Using Jupyter as a standalone tool](https://docs.astral.sh/uv/guides/integration/jupyter/#using-jupyter-as-a-standalone-tool)
* [Using Jupyter with a non-project environment](https://docs.astral.sh/uv/guides/integration/jupyter/#using-jupyter-with-a-non-project-environment)
* [Using Jupyter from VS Code](https://docs.astral.sh/uv/guides/integration/jupyter/#using-jupyter-from-vs-code)

### Jupyter kernels using virtual environments

See [How To Setup Jupyter Notebook In Conda Environment And Install Kernel - Python Engineer (python-engineer.com)](https://www.python-engineer.com/posts/setup-jupyter-notebook-in-conda-environment/). Although [I no longer recommend using conda in ExCL](https://docs.excl.ornl.gov/quick-start-guides/conda-and-spack-installation#installing-conda), the following steps are still a good way to manually create and use a kernel from Jupyter.

Create a python virtual environment and activate it. Then install `ipykernel` and then install the kernel for use in Jupyter.

```bash
pip install ipykernel
ipython kernel install --user --name=<any_name_for_kernel>
```

Use `jupyter kernelspec list` to view all the installed Jupyter kernels.

```bash
jupyter kernelspec list
```

To uninstall a Jupyter kernel use uninstall.

```bash
jupyter kernelspec uninstall <unwanted-kernel>
```

## Accessing a Jupyter Notebook Running on ExCL

A Jupyter notebook server running on ExCL can be accessed via a local web browser through port forwarding the Jupyter notebook's port. By default, this is port 8888 (or the next available port). This port might be in use if someone else is using running a notebook. You can specify the port with the `--port` flag when launching the Jupyter notebook. To use a different port just replace 8888 with the desired port number. In order to port forward from an internal node, you have to port forward twice, once from your machine to login.excl.ornl.gov and once again from the login node to the internal node (i.e. pcie).

### Detailed instructions for Linux/Mac

These instructions go over how to access a Jupyter notebook running on the pcie node in the ExCL Cluster. If you want to access a different system, then replace `pcie` with the system you intend to access.

1. Specify the ports that you intend to use. Choose a different number from the default so that you don't conflict with other users.

   ```
   export REMOTE_PORT=8888
   export LOCAL_PORT=8888
   ```
2. From your local machine connect to pcie using login.excl.ornl.gov as a proxy and local forward the jupyter port.

   ```
   ssh -L $LOCAL_PORT:localhost:$REMOTE_PORT -J $USER@login.excl.ornl.gov $USER@pcie
   ```
3. (Optional) Load the anaconda module if you don't have jupyter notebook installed locally.

   ```
   module load anaconda3
   ```
4. Launch the Jupyter server on pcie

   ```
   export REMOTE_PORT=8888
   jupyter notebook --port $REMOTE_PORT
   ```
5. Connect to the Jupyter notebook using a web browser on your local machine. Use the token shown in the output from running the Jupyter server. Url: `http://localhost:<local_port>/?token=<token>`. You can also configure jupyter to use a password with `jupyter notebook password` if you don't want to use the access tokens.

If you ssh client is too old for proxyjump to work, you can always break up the process into another step.

1. From your local machine connect to login.excl.ornl.gov and local port forward port 8888.

   ```
    $ ssh -L 8888:localhost:8888 <username>@login.excl.ornl.gov
   ```
2. From the login node connect to pcie and local port forward port 8888

   ```
    $ ssh -L 8888:localhost:8888 pcie
   ```
3. Launch the Jupyter server on pcie

   ```
    $ jupyter notebook
   ```
4. Connect to the Jupyter notebook using a web browser on your local machine. Use the token shown in the output from running the Jupyter server. Url: `http://localhost:8888/?token=<token>`

### Detailed instructions for Windows with MobaXterm

These instructions go over how to access a Jupyter notebook running on the pcie node in the ExCL Cluster.

1. From your local machine connect to login.excl.ornl.gov using MobaXterm.

   ![MobaXTerm SSH](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F4630a44b0239bf656dc296c98440778591197896.png?generation=1623954713782106\&alt=media)
2. Go to tools and click on MobaSSHTunnel. Use MobaSSHTunnel local forward port 8888.

   ![Click on MobaSSHTunnel](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2Ff7b70f68f843444329b5f40cd62fd59e14a0e0d4.png?generation=1624045162547604\&alt=media)

   Click on MobaSSHTunnel

   ![Click on New SSH Tunnel](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F743476da9022408a4207b69f7df334012cc54d73.png?generation=1623954714057728\&alt=media)

   Click on New SSH Tunnel

   ![Local port forward 8888](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F7841c957939f9bb0771d4d3f6268789e4543cbe6.png?generation=1623954714589756\&alt=media)

   Local port forward 8888

   ![Click the play button to start port forwarding](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F8bc66e968603116b20471a1d72fffa13ff45989d.png?generation=1623954715705299\&alt=media)

   Click the play button to start port forwarding
3. From the login node connect to pcie and local port forward port 8888

   ```
    $ ssh -L 8888:localhost:8888 pcie
   ```
4. Launch the Jupyter server on pcie

   ```
    $ jupyter notebook
   ```
5. Connect to the Jupyter notebook using a web browser on your local machine. Use the token shown in the output from running the Jupyter server. URL: `http://localhost:8888/?token=<token>`

### Detailed instructions for Windows with Visual Studio Code

These instructions go over how to access a Jupyter notebook running on the quad00 node in the ExCL Cluster using Visual Studio Code to handle port forwarding.

1. Open Visual Studio Code
2. Make sure you have the Remote - SSH extension installed.

   ![SSH Extension VS Code](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F690740323506992d7aeb7cbcc1ffd50d5dd59423.png?generation=1623954716225794\&alt=media)
3. Setup .ssh

   ![Navigate to the remote explorer settings.](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F09b40dacb7595c156701959da2880279160f872f.png?generation=1623954713818134\&alt=media)

   Navigate to the remote explorer settings.

   ![Chose the user .ssh config.](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2Ff481590baa9f508172d2cdffc05781b068346605.png?generation=1623954715801085\&alt=media)

   Chose the user .ssh config.

   ![Add the remote systems to connect to with the proxy command to connect through the login node.](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F7a2f13d64053952d3c8ec7de472c1d8598faa40b.png?generation=1623954720124940\&alt=media)

   Add the remote systems to connect to with the proxy command to connect through the login node.
4. Connect to the remote system and open the Jupyter folder.

   ![Connect step 1](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2Fa9c37128a09b3c9484953edaeb9e22cd0a983473.png?generation=1623954715049392\&alt=media)

   ![Open Folder](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2F12fe5db0b59f2d9b4e3ecd6daa5985c790e89c54.png?generation=1623954715597452\&alt=media)

   Open Folder
5. Run the Jupyter notebook using the built-in terminal.

   ![Run Jupyter](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2Fa1988caa59c0ed9445e0330d97cd71fba075e1ed.png?generation=1623954714397663\&alt=media)
6. Open the automatically forwarded port.

   ![Open Port](https://4244690715-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-McQDUQ3llzFCPZiz6Wq%2Fsync%2Ff96a9888cced6e1f09815b3d147b1c9dacce9209.png?generation=1623954714965831\&alt=media)