WSL 2 Installation Guide for jupyter-matlab-proxy

February 22, 2024 · View on GitHub

Windows® Subsystem for Linux® (WSL 2), available in Windows 10 and later, allows users to run Linux binaries in Windows. This repository shows how to install and start jupyter-matlab-proxy in WSL 2.

Table of Contents

Requirements
Set up WSL 2
Set up MATLAB
- Install MATLAB
- Add MATLAB executable path to system PATH
Install jupyter-matlab-proxy
Run MATLAB Code in Jupyter
Configure a Python Virtual Environment

Requirements

To use WSL 2, you need one of the following:

Windows 10
- For x64 systems: Version 1903 or later, with Build 18362.1049 or later.
- For ARM64 systems: Version 2004 or later, with Build 19041 or later.
Windows 11.

To check your Windows version, run the following command in command prompt:

winver

Set up WSL 2

Install WSL 2

Set up WSL 2 on your Windows machine:

From the Start menu, click Turn Windows features on or off.
Enable the following options:
- Virtual Machine Platform
- Windows Subsystem for Linux
Restart the system if prompted.

This activates WSL and the system's virtualization capability, which is required to run WSL 2.
Install the WSL 2 Linux Package. Open command prompt and run the following command:
```
wsl.exe --update
```

For details, see Install WSL(Microsoft).

Set up Linux Distribution

Install your Linux distribution, such as Debian or Ubuntu, from the Microsoft Store. MathWorks recommends Ubuntu 22.04 or run the following command:
```
wsl.exe --install Ubuntu-22.04
```
To start the Linux distribution, select it from the Start menu. Use the prompt to set a new username and password.
Check that the Linux version is 2. Open a new command prompt and run the following command:
```
wsl -l -v
```
If necessary, set the Linux version to 2 using
```
wsl --set-version <distro name> 2
```
For example:
```
wsl --set-version Ubuntu 2
```

Install System Dependencies

Install the system packages required to install and run MATLAB®.

Start the Linux Distro (Ubuntu 22.04) and update the package lists.
```
sudo apt update
```

Install xvfb, used to display plots and figures.

sudo apt install xvfb -y

For xvfb to work correctly, remount /tmp/.X11-unix with read-write permission:

sudo mount -o remount,rw /tmp/.X11-unix
# Adding it to the .bashrc file
echo `sudo mount -o remount,rw /tmp/.X11-unix` >> ~/.bashrc

Install Python.

sudo apt install python-is-python3 python3-pip wget unzip ca-certificates -y

Install MATLAB Package Manager.

wget https://www.mathworks.com/mpm/glnxa64/mpm 
chmod +x mpm

Set up MATLAB

Install MATLAB

Use MPM to install MATLAB. For example, to install MATLAB R2023a, navigate to the folder containing the mpm binary file and run this command:
```
./mpm install --release=R2023a --destination=/home/<username>/matlab --products MATLAB 
```
For more information on using MPM to install MATLAB, see MATLAB Package Manager.
Install the system dependencies that MATLAB requires. To see these dependencies, listed by MATLAB release & OS, refer to base-dependencies.txt in the corresponding MATLAB Dependencies folder.

For example, to install the dependencies for MATLAB R2023a on Ubuntu 22.04:
1. Navigate to 2023a -> Ubuntu22.04 -> base-dependencies.txt.
2. Download the base-dependencies file.
```
wget https://raw.githubusercontent.com/mathworks-ref-arch/container-images/main/matlab-deps/r2023a/ubuntu22.04/base-dependencies.txt
```
3. Install the dependencies.
```
cat base-dependencies.txt | xargs sudo apt install -y
```

Add MATLAB executable path to system PATH

jupyter-matlab-proxy expects the matlab executable to be present on the system PATH and will throw an error if it is unable to find the executable.

To make the matlab executable available on system PATH use the command:
```
sudo ln -fs <MATLAB_ROOT>/bin/matlab /usr/bin/matlab
```
where MATLAB_ROOT points to the folder in which MATLAB was installed. For example, the default value of MATLAB_ROOT in WSL 2 is /home/<username>/matlab.

Alternatively, you can update the system PATH to include the path to MATLAB binaries by executing the following command in your terminal.
```
export PATH=$PATH:/home/<username>/matlab/bin
```
/home/<username>/matlab/ is the path where the MATLAB is installed.
Execute the following command to show the current MATLAB path.
```
which matlab
```

Install matlab-proxy

Install jupyter-matlab-proxy, run:
```
python -m pip install jupyter-matlab-proxy
```
Note: in newer versions of Linux, such as Debian 12 or higher, you are unable to install python packages in externally-managed-environment. To use a virtual environment instead, follow the steps in Configure a Python Virtual Environment.
The packages are installed in /home/<username>/.local/bin. Add this location to the system path.
```
export PATH=$PATH:/home/<username>/.local/bin
```

Run MATLAB Code in Jupyter

Install Jupyter Notebook or JupyterLab:
```
# For Jupyter Notebook
python -m pip install notebook

# For JupyterLab 3
python -m pip install 'jupyterlab>=3.0.0,<4.0.0a0'
```
Note: The package lets you execute MATLAB code in both JupyterLab 3 and JupyterLab 4, but syntax highlighting and auto indentation are currently only supported in JupyterLab 3. To upgrade to JupyterLab 4, use:
```
python -m pip install jupyterlab
```

Open your Jupyter environment by starting Jupyter Notebook or JupyterLab.

# For Jupyter Notebook
jupyter notebook

# For JupyterLab
jupyter lab

Open one of the links highlighted in your web browser.
Now you can click MATLAB Kernel or Open MATLAB.
Click MATLAB Kernel and run the ver command.
You see a prompt to enter the license details.
MATLAB displays the output.

Refer to Installation and Get Started for more information on installing and using jupyter-matlab-proxy.

Configure a Python Virtual Environment

This guide shows how to install the jupyter-matlab-proxy package in a Python Virtual Environment.

Two commonly used environments are:

Python venv
conda

This guide uses conda as the environment manager.

Install miniconda.
Create a new python environment called r2023a by executing the command:
```
conda create -n r2023a python=3.11 -y
```
Activate the conda environment r2023a by executing the command:
```
conda activate r2023a
```

To install jupyter-matlab-proxy execute:

python -m pip install jupyter-matlab-proxy

Reactivate the conda environment.
```
conda activate r2023a
```
Verify that jupyter-matlab-proxy is running from the conda virtual environment.
```
which jupyter
```
```
/home/<username>/miniconda3/envs/r2023a/bin/jupyter
```
If you see the path listed as /home/<username>/.local/bin/jupyter, first uninstall the local version, then reinstall jupyter-matlab-proxy in the conda virtual environment.
Follow the steps in Run MATLAB code in Jupyter.