To run MATLAB® in Jupyter® inside a container, use the Dockerfile in this repository. The Dockerfile builds an image with MATLAB Integration for Jupyter (GitHub), based on a jupyter/base-notebook:ubuntu-22.04 base image from Jupyter Docker Stacks (GitHub), which ships with Python 3.11.
Access this Dockerfile either by directly downloading this repository from GitHub, or by cloning this repository and then navigating to the appropriate folder.
git clone https://github.com/mathworks-ref-arch/matlab-integration-for-jupyter.git
cd matlab-integration-for-jupyterBuild the container with a name and tag of your choice.
docker build -t mifj:R2024b .Run the container.
docker run -it -p 8888:8888 --rm mifj:R2024bTo open JupyterLab, use your browser to visit the address printed in your console of the format http://<hostname>:8888/?token=<token>. The hostname is the name of the computer running Docker, and the token is the secret token printed in the console.
For more information on running Jupyter images, see Jupyter Quick Start (Jupyter Docker Stacks).
By default, the Dockerfile installs MATLAB for the latest available MATLAB release, without any additional toolboxes or products, into the /opt/matlab folder, along with the Python package jupyter-matlab-proxy, which provides the MATLAB Integration for Jupyter.
To customize your build, use the options below.
Customize MATLAB Release, MATLAB Product List, MATLAB Install Location, License Server and other Python Packages
The Dockerfile supports the following Docker build-time variables.
| Argument Name | Description | Default value |
|---|---|---|
| MATLAB_RELEASE | The MATLAB release you want to install. | R2024b |
| MATLAB_PRODUCT_LIST | Products to install as a space-separated list. For more information, see MPM.md. For example: MATLAB Simulink Deep_Learning_Toolbox Fixed-Point_Designer. | MATLAB |
| MATLAB_INSTALL_LOCATION | The path to install MATLAB. | /opt/matlab |
| LICENSE_SERVER | The port and hostname of the machine that is running the Network License Manager, using the port@hostname syntax. For example: 27000@MyServerName | Unset |
| INSTALL_MATLABENGINE | Set this value to install the MATLAB Engine for Python into the image. | Unset |
| INSTALL_VNC | Set this value to install the jupyter-matlab-vnc-proxy, which allows you to connect to a traditional MATLAB desktop via VNC. | Unset |
To customize your build, use these arguments with the docker build command. See these examples:
To build an image for MATLAB R2019b, run:
docker build --build-arg MATLAB_RELEASE=R2019b -t mifj:R2019b .To build an image with MATLAB and Simulink, run:
docker build --build-arg MATLAB_PRODUCT_LIST='MATLAB Simulink' -t mifj:R2024b .To build an image with MATLAB installed at /opt/matlab, use this command.
docker build --build-arg MATLAB_INSTALL_LOCATION='/opt/matlab' -t mifj:R2024b .If you include the license server information with the docker build command, you do not have to provide it when running the container.
# Build container with the License Server.
docker build --build-arg LICENSE_SERVER=27000@MyServerName -t mifj:R2024b .
# Run the container, without providing license information.
docker run -it --rm -p 8888:8888 mifj:R2024b Alternatively, to provide the License Server information with docker run, you can use the environment variable MLM_LICENSE_FILE:
docker run -it --rm -p 8888:8888 -e MLM_LICENSE_FILE=27000@MyServerName mifj:R2024bFor more information on using the Network License Manager, see Use the Network License Manager for more information.
To build the default image along with the MATLAB Engine for Python for a given MATLAB Release, run:
docker build --build-arg INSTALL_MATLABENGINE=1 --build-arg MATLAB_RELEASE=R2024b -t mifj:R2024b .For more information, see:
- MATLAB Engine for Python (GitHub).
- Python Versions Compatible with MATLAB Products (MathWorks).
- The Dockerfile in this repository an image based on Python 3.11 and the MATLAB Engine for Python only supports this version from MATLAB R2023b onwards.
- If the MATLAB Engine for Python fails to install, this will not fail the
docker buildcommand.
To build the default image along with the MATLAB Integration for Jupyter using VNC, run:
docker build --build-arg INSTALL_VNC=1 -t mifj:R2024b .For more information, see MATLAB Integration for Jupyter using VNC*(GitHub)*.
There are 3 ways to include MATLAB in your container image.
- Install MATLAB using MATLAB Package Manager (mpm).
- Mount MATLAB on the Image.
- Bring Your Own Image (BYOI)
- Copy MATLAB installation from another container image.
The default configuration of the Dockerfile uses mpm to install MATLAB and the specified toolboxes into the container image as described in the sections above.
To provide a MATLAB installation to the container via volume or bind mount, instead of installing MATLAB inside the image, follow the instructions below.
The Dockerfile assumes that you want to mount MATLAB in the /opt/matlab folder. Use the Build Argument MATLAB_INSTALL_LOCATION to specify a custom location within the container where you want to mount MATLAB.
Use the Dockerfile Build Arguments MOUNT_MATLAB and MATLAB_RELEASE with your docker build command.
docker build --build-arg MOUNT_MATLAB=1 \
--build-arg MATLAB_RELEASE=R2024b \
-t mifj:mounted .The MATLAB_RELEASE argument ensures that the system dependencies required for MATLAB are installed in the container.
Note: When you are mounting MATLAB on the container at run time, you cannot install MATLAB Engine for Python at build time.
If MATLAB is installed in /usr/local/MATLAB/R2024b on your local machine, you can bind mount this folder to /opt/matlab using the command shown below:
docker run -it --rm -v /usr/local/MATLAB/R2024b:/opt/matlab:ro -p 8888:8888 mifj:mounted For more information, see Bind Mounts (Docker).
Access the Jupyter Notebook by following one of the URLs displayed in the output of the docker run command.
This option is useful when you want to minimize the size of the container as installing MATLAB and its toolboxes can make the image large (greater than 10GB), depending on the MATLAB toolboxes installed.
To copy an existing MATLAB installation from another container image, specify the image name with the Docker Build Arguments MATLAB_IMAGE_NAME and MATLAB_RELEASE as shown below:
# Copies MATLAB from the Dockerhub Image "mathworks/matlab:r2024b" into the image being built.
docker build --build-arg MATLAB_IMAGE_NAME=mathworks/matlab:r2024b \
--build-arg MATLAB_RELEASE=R2024b \
-t mifj:copied .The MATLAB_RELEASE argument, ensures that the system dependencies required for MATLAB, are installed into the container.
You can download several Docker images based on this Dockerfile from the GitHub Container Registry.
These images are based on jupyter/base-notebook:ubuntu-22.04 and include:
- MATLAB
- MATLAB Integration for Jupyter
- MATLAB Integration for Jupyter using VNC
- MATLAB Engine for Python
- Only available in pre-built images newer than R2023b
- See Different Versions of OS or Python for more information on installing the engine for older versions of MATLAB.
Available Tags: R2024b, R2024a, R2023b, R2023a, R2022b
Docker Pull Command:
# Substitute the tag with your desired version of MATLAB.
docker pull ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-matlab-notebook:R2024bThese images are based on jupyter/base-notebook:ubuntu-22.04 and include:
- MATLAB Integration for Jupyter
- MATLAB Integration for Jupyter using VNC
- MATLAB Engine for Python
- Only available in pre-built images newer than R2023b
- See Compatibility for Different Versions of OS or Python for more information on installing the engine for older versions of MATLAB.
Available Tags: R2024b, R2024a, R2023b, R2023a, R2022b
Docker Pull Command:
# Substitute the tag with your desired version of MATLAB.
docker pull ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-mounted-matlab-notebook:R2024bUse the correct version of the image based on the MATLAB release you are mounting on the image.
For example to mount R2022b from your local machine, that is installed in /usr/local/MATLAB/R2022b, use the following docker run command:
docker run -it --rm -v /usr/local/MATLAB/R2022b:/opt/matlab:ro -p 8888:8888 ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-mounted-matlab-notebook:R2022bTo build on older versions of Ubuntu or Python, update the base image used in the Dockerfile with the tags specified in the Jupyter Docker Stacks repository.
For example, this page lists 4d70cf8da953 as the tag for an image with Python 3.10 on Ubuntu 22.04.
To build an image with this base layer, update Line 66 in the Dockerfile to FROM quay.io/jupyter/base-notebook:4d70cf8da953.
This might be useful if your workflow depends on older versions of Python. For example the MATLAB Engine for Python only supports Python 3.11 from R2023b. Installing it on MATLAB releases older than R2023b would require an older version of Python, and you can use the approach above to build an image with the desired Python version. For more information about Python compatibility for MATLAB Products, see Python Versions for MATLAB Products.
To verify that the release of MATLAB you are installing is supported for your operating system, consult the MATLAB Dependencies repository. For example, R2024b is currently the only MATLAB Release which supports Ubuntu 24.04.
To submit an enhancement request or request technical support, create an Issue.
Copyright 2020-2024 The MathWorks, Inc.
