Jupyter MATLAB Proxy¶

Overview¶

Jupyter MATLAB Proxy (jupyter-matlab-proxy) lets you run MATLAB inside JupyterLab, either as a notebook kernel or as a full graphical MATLAB Desktop streamed into a browser tab.

Setting Up the Environment¶

Create a conda environment

A dedicated environment is recommended, but not required — you can use any existing environment or base.

conda create -n matlab python=3.10 -y
conda activate matlab

Install jupyter-matlab-proxy

python -m pip install jupyter-matlab-proxy

Verify the MATLAB kernelspec

The package installs a kernelspec utility that points the MATLAB kernel at the correct Python executable for this environment.

install-matlab-kernelspec

The utility also allows you to preview changes without applying them (--preview), or to reset the kernelspec back to its default configuration (--reset). For more information about the utility, use --help:

install-matlab-kernelspec --help

Install JupyterLab

If you don't already have it installed:

python -m pip install jupyterlab

Running on a Compute Node¶

Start an interactive session and load both MATLAB and your conda environment before launching Jupyter.

Interactive session

srun --partition=gpu_short --gres=gpu:1 --time=04:00:00 --pty bash

module load matlab/R2026a
conda activate matlab

jupyter lab --no-browser --ip=0.0.0.0 --port=8888

Port may already be in use

8888 is just an example. Since --ip=0.0.0.0 listens on all interfaces, another user's job on the same node may already be using that port. If so, pick a different one.

Running Jupyter on PERUN

See https://wiki.perun.tuke.sk/perun/env/jupyter for more details on running Jupyter notebooks on PERUN.

Accessing JupyterLab from Your Local Machine¶

Since Jupyter is running on a compute node, not directly reachable from outside the cluster, tunnel through the login node.

SSH port forward

ssh -L 8888:<compute-node-name>:8888 <username>@login01.perun.tuke.sk

Then open the URL Jupyter printed at startup (with the token), replacing the hostname with localhost:

http://localhost:8888/lab?token=<your-token>

Find your compute node

squeue -u <username>

The NODELIST column shows which node your job landed on.

Using the MATLAB Kernel¶

Once JupyterLab is open, create a new notebook and select MATLAB Kernel. Cells execute MATLAB code directly.

Simple sanity check

disp('MATLAB is running');
fprintf('Version: %s\n', version);
a = [1 2 3];
b = [4 5 6];
fprintf('Dot product: %d\n', dot(a, b));

Using the Full MATLAB Desktop¶

Click Open MATLAB from the JupyterLab launcher to open a full graphical MATLAB Desktop in a new browser tab, streamed via matlab-proxy.

Enabling Debug Logging¶

If something isn't starting correctly, enable verbose logging before launching Jupyter.

Debug logging

export MWI_JUPYTER_LOG_LEVEL="DEBUG"
jupyter lab --no-browser --ip=0.0.0.0 --port=8888

Log levels available: NOTSET, DEBUG, INFO, WARN, ERROR, CRITICAL (default is INFO).

Troubleshooting¶

Unable to find Xvfb on the system PATH

This is a system-level dependency issue. Contact the cluster admins.

MATLAB cannot be run on login nodes

If you see this error when loading the MATLAB module, you're on a login node. Start an interactive session with srun first, or submit via sbatch.

Run the official diagnostic script

MathWorks ships a troubleshooting script that checks your MATLAB, Python, Xvfb, and Jupyter setup in one pass. Run it on a compute node with the MATLAB module loaded:

curl -fsSL -o troubleshooting.py https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py
python troubleshooting.py

More Information¶

Documentation

Official jupyter-matlab-proxy repository and documentation:

https://github.com/mathworks/jupyter-matlab-proxy