HOWTO: Use a Conda/Virtual Environment With Jupyter

The IPython kernel for a Conda/virtual environment* must be installed on Jupyter prior to use.

*See create conda/virtual environment if there is not already an environment that has been created.

Install kernel

Load the preferred version of Python or Miniconda3 using the command:

module load python

or

module load miniconda3

Replace "python" or "miniconda3" with the appropriate version, which could be the version you used to create your Conda/venv environment. You can check available Python versions by using the command:

module spider python

Run one of the following commands based on how your Conda/virtual environment was created. Replace "MYENV" with the name of your Conda environment or the path to the environment.

If the Conda environment was created via conda create -n MYENV command, use the following command:

~support/classroom/tools/create_jupyter_kernel conda MYENV

If the Conda environment was created via conda create -n /path/to/MYENV command, use the following command:

~support/classroom/tools/create_jupyter_kernel conda /path/to/MYENV

If the Python virtual environment was created via python3 -m venv /path/to/MYENV command, use the following command

~support/classroom/tools/create_jupyter_kernel venv /path/to/MYENV

The resulting kernel name appears as "MYENV [/path/to/MYENV]" in the Jupyter kernel list. You can change the display name by appending a preferred name in the above commands. For example:

~support/classroom/tools/create_jupyter_kernel conda MYENV "My Research Project"

This results in the kernel name "My Research Project" in the Jupyter kernel list.

Install Jupyterlab Debugger kernel

According to Jupyterlab page, debugger requires ipykernel >= 6. Please create your own kernel with conda using the following commands:

$ module load miniconda
$ conda create -n jupyterlab-debugger -c conda-forge "ipykernel>=6" xeus-python
$ ~support/classroom/tools/create_jupyter_kernel conda jupyterlab-debugger

You should see a kernelspec 'conda_jupyterlab-debugger' created in home directory. Once the debugger kernel is done, you can use it:
1. go to OnDemand
2. request a JupyterLab app with kernel 3
3. open a notebook with the debugger kernel.
4. you can enable debug mode at upper-right kernel of the notebook

Remove kernel

If the envirnoment is rebuilt or renamed, users may want to erase any custom jupyter kernel installations.

Be careful! This command will erase entire directories and all files within them.
rm -rf ~/.local/share/jupyter/kernels/${MYENV}

Manually install kernel

If the create_jupyter_kernel script does not work for you, try the following steps to manually install kernel:

# change to the proper version of python
module load python  

# replace with the name of conda env           
MYENV=useful-project-name

# Activate your conda/virtual environment
## For Conda environment
source activate $MYENV

# ONLY if you created venv instead of conda env
## For Python Virtual environment
source /path/to/$MYENV/bin/activate

# Install Jupyter kernel 
python -m ipykernel install --user --name $MYENV --display-name "Python ($MYENV)"

 

Supercomputer: 
Service: 
Fields of Science: