HOWTO: Use a Conda/Virtual Environment With Jupyter

The IPython kernel for a Conda/virtual environment must be installed on Jupyter prior to use. This tutorial will walk you though the installation and setup procedure.

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 -p /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.

You should now be able to access the new Jupyter kernel on OnDemand in a jupyter session. See Usage section of Python page for more details on accessing the Jupyter app.

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

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
    
# create the cpnda enironment
conda create -n $MYENV
    
# 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)"

Remove kernel

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

rm -rf ~/.local/share/jupyter/kernels/${MYENV}