Adding Conda Environments as Jupyter Kernels

To have a conda environment show as a kernel in Jupyter, one more step is needed.

Ensure the environment has the jupyterlab package

In order to use an environment in Jupyter, we need to make sure we install the jupyterlab package in the environment:

mamba install jupyterlab

Copy the template_kernel Folder to Your Path

On HiPerGator, Jupyter looks in two places for kernels when you launch a notebook:

1. /apps/jupyterhub/kernels/ for the globally available kernels that all users can use. (Also a good place to look for troubleshooting getting your own kernel going)
2. ~/.local/share/jupyter/kernels for each user. (Again, your home directory and the .local folder is hidden since it starts with a dot)

You may need to make the ~/.local/share/jupyter/kernels directory:

mkdir -p ~/.local/share/jupyter/kernels

Copy the /apps/jupyterhub/template_kernel folder into your ~/.local/share/jupyter/kernels directory (change the folder name to correspond to your environment name):

cp -r /apps/jupyterhub/template_kernel/ ~/.local/share/jupyter/kernels/my_env

Edit the template_kernel files

The template_kernel directory has four files: the run.sh and kernel.json files will need to be edited in a text editor. The logo-64X64.png and logo-32X32.png are icons for your kernel to help visually distinguish it from others. You can upload icons of those dimensions to replace the files, but they need to be named with those names.

Edit the kernel.json File

It is easiest to change into the folder you copied above:

cd ~/.local/share/jupyter/kernels/my_env/

Tip

Before editing the kernel.json file, we want to get the path to the run.sh file. Use the pwd command to get that and copy the path. e.g.:

[username@login8 my_env]$ pwd
/home/magitz/.local/share/jupyter/kernels/my_env
[username@login8 my_env]$

As an example, we can use nano to edit these files:

nano kernel.json

The template has most of the information and notes on what needs to be updated. Edit the file to look like:

{
    "language": "python",
    "display_name": "My Environment",
    "argv": [
    "~/.local/share/jupyter/kernels/my_env/run.sh",
    "-f",
    "{connection_file}"
    ]
}

Edit the run.sh File

Tip

The run.sh file needs the path to the python application that is in our environment. The easiest way to get that is to make sure the environment is activated and run the command: which python

The path it outputs should look something like: /blue/mygroup/user/.conda/envs/my_env/bin/python. Copy that path.

Edit the run.sh file with nano:

nano run.sh

The file should looks like this, but with your path:

#!/usr/bin/bash
exec /blue/mygroup/user/.conda/envs/my_env/bin/python -m ipykernel "$@"

Your kernel should be there ready for you to use in Jupyter. It will take a minute or two to show up in an active session, or if you reload the page it should show up.

Troubleshooting Kernels

If you kernel doesn't display, or won't launch, check the Jupyter output log.

In Open on Demand, each session has a card with a link to the Session ID.

Click on that link and open the output.log file. That log file will often provide clues as to why kernels cannot launch.