Run MATLAB in GitHub Codespaces

This repository shows how to run MATLAB® in GitHub™ Codespaces.

Get Started

A codespace (GitHub Docs) is a development environment you can run in the cloud. Codespaces run in Docker containers called development containers, or dev containers (GitHub Docs). You can customize your codespace by modifying devcontainer.json, the configuration file of the dev container.

The examples in this repository show different ways you can configure your dev containers to run MATLAB in codespaces. For each example, you can find the corresponding devcontainer.json configuration file in the .devcontainer folder.

1. Using the MATLAB Image on Docker Hub
2. Using the MATLAB Image on Docker Hub and MATLAB Proxy
3. Using the MATLAB Devcontainer Feature
4. Using MATLAB with Jupyter
5. Using MATLAB Dockerfile

Using the MATLAB Image on Docker Hub

To run a dev container with MATLAB using the MATLAB Image on Docker Hub, use this devcontainer.json configuration:

{
  "name": "MATLAB",
  "image": "mathworks/matlab:latest",
  "waitFor": "updateContentCommand",
  "updateContentCommand": {
    "install-git": "sudo apt-get update && sudo apt-get install git -y"
  }
}

Using the MATLAB Image on Docker Hub and MATLAB Proxy

To run a dev container with the MATLAB Image on Docker Hub and matlab-proxy, which starts MATLAB in a browser tab, use this devcontainer.json configuration:

{
  "name": "MATLAB",
  "image": "mathworks/matlab:latest",
  "hostRequirements": {
    "cpus": 4
  },
  "portsAttributes": {
    "8888": {
      "label": "MATLAB",
      "onAutoForward": "openBrowser"
    }
  },
  "waitFor": "updateContentCommand",
  "updateContentCommand": {
    "install-git": "sudo apt-get update && sudo apt-get install git -y",
    "update-matlab-proxy": "sudo python3 -m pip install --upgrade pip matlab-proxy"
  },
  "postStartCommand": "run.sh -browser"
}

The postStartCommand starts matlab-proxy and onAutoForward opens a browser tab running MATLAB.

Note: Depending on your system configuration, you might need to click on the link presented in the VSCode terminal to start the browser session.

You can run the dev container configured above in Codespaces:

Using the MATLAB Devcontainer Feature

You can add functionality to your dev containers by adding self-contained units of code called Features (GitHub). For example, to install MATLAB R2024b in your dev container with the MATLAB Feature (GitHub), use this devcontainer.json configuration:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/mathworks/devcontainer-features/matlab": {}
  }
}

This configuration installs the MATLAB Feature on a ubuntu base image, with default settings. To customize the settings, modify the MATLAB Feature Options (GitHub). For example, to install MATLAB R2023a instead of R2024b, as well as the Symbolic Math Toolbox, use this configuration:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/mathworks/devcontainer-features/matlab": {
      "release": "r2023a",
      "products": "MATLAB Symbolic_Math_Toolbox"
    }
  }
}

You can run MATLAB R2024b with this configuration in Codespaces:

Using MATLAB with Jupyter

To use MATLAB in JupyterLab, running in codespaces, you can configure your dev container to include MATLAB Integration for Jupyter. Use one of these methods:

1. Use the MATLAB Integration for Jupyter image:

{
  "name": "R2024a MATLAB Integration for Juptyer Prebuilt Image",
  "image": "ghcr.io/mathworks-ref-arch/matlab-integration-for-jupyter/jupyter-matlab-notebook:r2024a",
  "hostRequirements": {
    "cpus": 4
  }
}

2. Use the MATLAB Integration for Jupyter Dockerfile (GitHub). Customize your args as desired:

{
  "name": "MATLAB Integration for Jupyter Dockerfile",
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      "MATLAB_RELEASE": "r2023b",
      "MATLAB_PRODUCT_LIST": "MATLAB Symbolic_Math_Toolbox",
      "PYTHON_VERSION": "3.10"
    }
  },
  "hostRequirements": {
    "cpus": 4
  }
}

3. Use the MATLAB Feature and customize the MATLAB Feature Options (GitHub) to install MATLAB, Python, JupyterLab, and the MATLAB Integration for Jupyter. For example:

{
  "name": "Using MATLAB with Jupyter",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "hostRequirements": {
    "cpus": 4
  },
  "features": {
    "ghcr.io/mathworks/devcontainer-features/matlab": {
      "release": "r2024b",
      "products": "MATLAB Symbolic_Math_Toolbox",
      "installJupyterMatlabProxy": true,
      "installMatlabEngineForPython": true
    },
    "ghcr.io/devcontainers/features/python": {
      "version": "os-provided",
      "installJupyterlab": true,
      "configureJupyterlabAllowOrigin": "*"
    }
  },
  "containerUser": "codespace"
}

You can run the dev container configured above in Codespaces:

Using MATLAB Dockerfile

To run a dev container using the MATLAB Dockerfile and matlab-proxy, use this devcontainer.json configuration:

{
  "name": "Using matlab-dockerfile",
  "build": {
    // See: https://github.com/mathworks-ref-arch/matlab-dockerfile
    "dockerfile": "Dockerfile",
    "args": {
      "MATLAB_RELEASE": "r2024b",
      "MATLAB_PRODUCT_LIST": "MATLAB Symbolic_Math_Toolbox"
    }
  },
  "hostRequirements": {
    "cpus": 4
  },
  "portsAttributes": {
    "8888": {
      "label": "MATLAB",
      "onAutoForward": "openBrowser"
    }
  },
  "waitFor": "updateContentCommand",
  "updateContentCommand": {
    "install-git-and-proxy": "sudo apt-get update && sudo apt-get install --no-install-recommends -y git python3 python3-pip xvfb && sudo python3 -m pip install --upgrade matlab-proxy"
  },
  "postStartCommand": "env MWI_APP_PORT=8888 matlab-proxy-app"
}

You can run this dev container in Codespaces:

Related Links

• Overview of Codespaces (GitHub)
• Development Container Features (GitHub)
• Development Container Specification (Microsoft®)
• Setting Your Default Editor for Codespaces (GitHub)
• Run Dev Containers in VS Code (VS Code Docs)

---

Copyright 2024 The MathWorks, Inc.

---