/
Using Jupyterhub Kernels from the CLI

Using Jupyterhub Kernels from the CLI

The available JupyterHub Python kernel environments can also be used directly from a terminal command line (CLI). This is useful for running Python scripts, command-line bioinformatics tools, batch jobs, or interactive Python sessions without opening JupyterHub.

The environments are installed under /opt/jupyterhub-kernels on all machines. Each JupyterHub Python kernel corresponds to a standard Python virtual environment in that directory. Use the same environment you would select as a kernel in JupyterHub for your needs.

Available environments

JupyterHub kernel

Command-line environment

JupyterHub kernel

Command-line environment

Python 3.12 (Bioinformatics)

/opt/jupyterhub-kernels/python312-bio

Python 3.12 (ML/CPU)

/opt/jupyterhub-kernels/python312-ml-cpu

Python 3.12 (ML-JAX/CPU)

/opt/jupyterhub-kernels/python312-ml-jax-cpu

Python 3.12 (ML/GPU NVIDIA)

/opt/jupyterhub-kernels/python312-ml-gpu-nvidia

Python 3.12 (ML-JAX/NVIDIA)

/opt/jupyterhub-kernels/python312-ml-jax-nvidia

Python 3.12 (ML/GPU AMD ROCm)

/opt/jupyterhub-kernels/python312-ml-gpu-amd

Python 3.12 (ML-JAX/ROCm)

/opt/jupyterhub-kernels/python312-ml-jax-rocm

Since they are shared and centrally managed, virtual environments under /opt/jupyterhub-kernels are read-only: users cannot install, upgrade, or remove packages. This restriction ensures that environments continue to work consistently for all users.

Do not use sudo pip, and do not attempt to change permissions inside /opt/jupterhub-kernels.

If a package would be broadly useful, ask us (rctf-support@utexas.edu) to consider adding it to the appropriate shared environment. If you need packages only for your own project, create a personal virtual environment.

Method 1: Activate an environment

Activating an environment changes your shell so that commands such as python, pip, and installed command-line programs refer to that environment.

For general bioinformatics work:

source /opt/jupyterhub-kernels/python312-bio/bin/activate

Your command prompt will normally change to show the active environment. You can then run Python:

python

Run a script:

python analysis.py

Or use a command-line program installed in the environment:

ipython

To verify which Python is active:

which python python --version

The result from which python should point inside /opt/jupyterhub-kernels, for example:

/opt/jupyterhub-kernels/python312-bio/bin/python

When finished, leave the environment with:

deactivate

Activation affects only the current terminal session. Opening another terminal will not automatically activate the environment.

Activation examples

Bioinformatics:

source /opt/jupyterhub-kernels/python312-bio/bin/activate python analysis.py

CPU-based PyTorch or TensorFlow:

source /opt/jupyterhub-kernels/python312-ml-cpu/bin/activate python train_model.py

CPU-based JAX:

source /opt/jupyterhub-kernels/python312-ml-jax-cpu/bin/activate python jax_analysis.py

NVIDIA GPU with PyTorch:

source /opt/jupyterhub-kernels/python312-ml-gpu-nvidia/bin/activate python train_model.py

NVIDIA GPU with JAX:

source /opt/jupyterhub-kernels/python312-ml-jax-nvidia/bin/activate python jax_analysis.py

AMD GPU with PyTorch:

source /opt/jupyterhub-kernels/python312-ml-gpu-amd/bin/activate python train_model.py

AMD GPU with JAX:

source /opt/jupyterhub-kernels/python312-ml-jax-rocm/bin/activate python jax_analysis.py

Method 2: Run the environment's Python directly

You do not have to activate an environment to use it. You can run its Python interpreter directly by using the complete path.

For example:

/opt/jupyterhub-kernels/python312-bio/bin/python analysis.py

For a CPU-based machine-learning script:

/opt/jupyterhub-kernels/python312-ml-cpu/bin/python train_model.py

For JAX on an NVIDIA GPU:

/opt/jupyterhub-kernels/python312-ml-jax-nvidia/bin/python jax_analysis.py

This method is particularly useful in shell scripts, scheduled jobs, and batch-processing systems because it explicitly records which Python environment should be used.

For example:

#!/bin/bash set -euo pipefail PYTHON=/opt/jupyterhub-kernels/python312-bio/bin/python "$PYTHON" "$HOME/projects/genomics/process_samples.py" \ --input "$HOME/data/samples.csv" \ --output "$HOME/results"

Using the full path also avoids accidentally running the operating system's default Python or a different virtual environment.

Using an environment in a script's shebang

A script can specify a particular environment directly in its first line:

#!/opt/jupyterhub-kernels/python312-bio/bin/python import pandas as pd data = pd.read_csv("samples.csv") print(data.describe())

Make the script executable:

chmod +x summarize_samples.py

Then run it directly:

./summarize_samples.py

This makes the script consistently use the selected shared environment, regardless of which Python is active in the user's shell.

A fixed shebang can be convenient, but it makes the script specific to machines where the environment exists at that exact path. For scripts that will be distributed to other systems, or run across multiple heterogeneous nodes, documenting the required environment and invoking it explicitly may be more portable.

Using the environments from shell scripts

For repeatable scripts, using an explicit interpreter path is usually better than relying on activation.

Recommended:

#!/bin/bash set -euo pipefail VENV=/opt/jupyterhub-kernels/python312-bio "$VENV/bin/python" analysis.py

Also valid:

#!/bin/bash set -euo pipefail source /opt/jupyterhub-kernels/python312-bio/bin/activate python analysis.py

The explicit-path version is generally easier to understand and less affected by shell startup files, aliases, or an already-active virtual environment.

Using environment variables and additional programs

Activating a virtual environment primarily changes PATH; it does not create a separate operating-system session. Your normal environment variables, home directory, files, and permissions remain unchanged.

For example:

source /opt/jupyterhub-kernels/python312-bio/bin/activate export PROJECT_DIR="$HOME/projects/genomics" python "$PROJECT_DIR/analyze.py"

You can still run ordinary system commands:

grep sort vi samtools

Whether a non-Python command is available depends on what is installed on the host system or in the selected environment.

Troubleshooting

python still points to the wrong location

Deactivate any previously active environment and try again:

deactivate source /opt/jupyterhub-kernels/python312-bio/bin/activate

You can always bypass activation by using the complete path:

/opt/jupyterhub-kernels/python312-bio/bin/python analysis.py

Using import torch, import tensorflow, or import jax fails

These packages are not installed in every environment.

Use:

  • python312-ml-cpu for CPU PyTorch, TensorFlow, and Transformers

  • python312-ml-jax-cpu for CPU JAX

  • python312-ml-gpu-nvidia for PyTorch and related software on NVIDIA GPUs

  • python312-ml-jax-nvidia for JAX on NVIDIA GPUs

  • python312-ml-gpu-amd for PyTorch and related software on AMD GPUs

  • python312-ml-jax-rocm for JAX on AMD GPUs

A GPU environment reports no GPU

Possible causes include:

  • The command is running on a CPU-only machine.

  • The environment does not match the GPU type.

  • The GPU is not visible to the current job or session (not in the render or video group).

  • The machine has an unsupported or partially supported GPU (e.g. AMD MI-50).

  • Required drivers or runtime services are unavailable.

pip install reports a permission error

The shared environment is read-only. Do not use sudo or attempt to change its permissions.

Request that a broadly useful package be added centrally, or create a personal environment for project-specific packages.

An environment is active, but a command is missing

The command may not be installed in that particular environment. Check:

command -v command-name

And inspect the environment's bin directory:

ls /opt/jupyterhub-kernels/python312-bio/bin

A Python module may also be runnable with python -m even if it does not provide a separate command:

python -m module_name

Quick examples

Start an interactive bioinformatics Python session:

source /opt/jupyterhub-kernels/python312-bio/bin/activate python

Run a pandas script without activating anything:

/opt/jupyterhub-kernels/python312-bio/bin/python summarize_data.py

Run a CPU PyTorch script:

/opt/jupyterhub-kernels/python312-ml-cpu/bin/python train.py

Run a JAX script on an NVIDIA GPU node:

/opt/jupyterhub-kernels/python312-ml-jax-nvidia/bin/python model.py

Check which Python an activated shell is using:

python -c 'import sys; print(sys.executable)'

Leave an activated environment:

deactivate

Recommended practice

For interactive work, activate the environment:

source /opt/jupyterhub-kernels/python312-bio/bin/activate

For scripts, scheduled jobs, and reproducible command lines, use the full interpreter path:

/opt/jupyterhub-kernels/python312-bio/bin/python analysis.py

In both cases, choose the same environment that you would choose as a JupyterHub kernel.