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 jupyter-matlab-proxy
- Run MATLAB Code in Jupyter
- Configure a Python Virtual Environment
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 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).
-
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 newcommand prompt
and run the following command:wsl -l -v
If necessary, set the Linux version to
2
usingwsl --set-version <distro name> 2
For example:
wsl --set-version Ubuntu 2
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
-
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:
-
Navigate to
2023a
->Ubuntu22.04
->base-dependencies.txt
. -
Download the base-dependencies file.
wget https://raw.githubusercontent.com/mathworks-ref-arch/container-images/main/matlab-deps/r2023a/ubuntu22.04/base-dependencies.txt
-
Install the dependencies.
cat base-dependencies.txt | xargs sudo apt install -y
-
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 ofMATLAB_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
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
-
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
orOpen MATLAB
. -
Click
MATLAB Kernel
and run thever
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
.
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 reinstalljupyter-matlab-proxy
in the conda virtual environment. -
Follow the steps in Run MATLAB code in Jupyter.
Copyright 2024 The MathWorks, Inc.