Home | Projects | Notes | Misc | Events | Github/ Forgejo/ Codeberg

Running MATLAB in Docker, properly

Date: 18th September 2025

Why MATLAB in Docker

I use ArchLinux (btw) as my daily driver distro. Actually EndeavourOS for the last year or so, but whatever. I use a rolling release distro. I like having the newest versions of packages and the AUR and the ArchWiki are simply awesome. Apart from my personal learning curve, this choice has presented problems exactly three times. Two of which, unsurprisingly, involved some exoteric setups and the NVIDIA drivers.
The first one of which was when I first started using a DisplayLink adapter on my old laptop which only had one HDMI port, but I wanted to use two monitors with. Once I figured that out it was smooth sailing. The second one was when, for a time, I tried running some modified drivers to split my GPU into multiple vGPUs to run a Windows 10 VM for the sole purpose of using Autodesk Fusion. I then tried using a further patch to the patched drivers to use vGPUs and the GPU on the host at the same time. All of it while running a Tesla M40 datacenter GPU with no video output in my desktop and an AMD Radeon HD5450 for the sole purpose of having a video output and then using PRIME Offloading to do the actual computation on the Tesla.
An unorthodox setup to say the least. Worked fine when it worked, borked every other week with kernel updates, even with dkms, even with a LTS kernel. It seemed to work fine on Debian though, haven’t tried it for long. I also have since upgraded to a RTX3060 with 12GB of VRAM, figuring it was best to have CUDA support for probable future uni work. I guessed right.

Anyhow, the third time where my distro of choice was actually a problem involed, unsurprisingly, MATLAB. It was a couple of months ago, when an update in glibc broke release R2024b). Looked like R2025a was no dice too. Neither on my desktop nor on my laptop. I even tried opening a ticket with support, which didn’t have a clue what the problem was and suggested uninstalling and reinstalling and messing with permissions on files I’d rather not touch. All the while, no meaningful error messages in the logs. Gotta love MATLAB, man.

Luckily I had submitted and discussed my homeworks for my Multivariable Feedback Control course a week prior. Had this problem prevented me from taking that exam I would have probably gone on a rampage. It was about to prevent me to start working on the project for my Robotics 2 course though.

Okay, isolate the problem to glibc or execstack or whatever you want. It doesn’t look like something I can properly fix myself, gotta wait for a MATLAB update. Like that’s gonna come. Also I unfortunately really need MATLAB for my uni work and also I really, really can’t be rolling a dice every time I run sudo pacman -Syu to discover whether I’ll need to spend the following week fixing MATLAB.

So what, containers? Containers do seem like the perfect choice. An immutable, stable environment made just perfectly for that single program to run? Sign me in.

The ArchWiki even has a paragraph dedicated to running MATLAB in a sytemd-nspawn container for situations exactly like mine. They even say that in the article, see? They do know their chickens, as a teacher of mine used to say.

MATLAB can be run within a systemd-nspawn container to maintain a static system and avoid the library issues that often plague matlab installs after significant updates to libraries in Arch.

Gotta love the ArchWiki, there’s an entry for literally everything.

Unfortunately this is a pain to run. Mostly because the MATLABProductAuthorizer loved to simply crash before logging in with my uni credentials, or after logging in with my uni credentials. On the rare occasions it managed to authenticate me properly, MATLAB wouldn’t recognize the license and exit after a while. There was also the slight problem of passing video through to the host in a somewhat seamless manner. I run Wayland (KDE Plasma), the instructions work well for X11 forwarding. Whatever, I can use Xephyr. Or call up a new kwin --xwayland and forward to that (neat trick, this, for forwarding X11 Windows to a Wayland desktop. You can even add some window rules in Plasma to not show borders, then it is properly seamless. It does mess up my keyboard shortcuts after exiting though). Also some problems with permissions and bind mounting directories? At some point I lost track to be honest.

Then I discovered that are some actually official docker images for MATLAB on Docker Hub. Neat, wasn’t expecting that. These are actually not a pain to run. Also neat. Also wasn’t expecting that. Give the docker hub page a read, it has a few interesting hints.

I like using docker compose instead of just remembering a string of parametes to a docker run command, so here a basic one of mine

docker-compose-matlab-r2025a.yml 
---

services:
  matlab:
    container_name: matlab_r2025a
    image: mathworks/matlab:r2025a
    ports:
      - 5901:5901
      - 6080:6080
      - 8888:8888
    volumes:
      - matlab_data:/home/matlab
      - /home/emamaker/:/home/emamaker
      #- /tmp/.X11-unix:/tmp/.X11-unix:ro
    environment:
      - TZ=Europe/Rome
    shm_size: '8gb'
#    command: -vnc
    command: -browser

volumes:
  matlab_data:

The -browser parameters lets you use the UI in a browser, at localhost:8888. There’s also ways to use VNC or X11 forwarding. I personally prefer the browser, because it can also be accessed from other machines in the LAN. This means I can run MATLAB headless on my desktop and use it on my laptop. My new laptop is a workhorse for its size, but sometimes the desktop is just faster. The shm_size parameter defines how much RAM MATLAB can use.

Custom build for installing toolboxes

git clone https://github.com/mathworks-ref-arch/matlab-dockerfile

cd alternates/building-on-matlab-docker-image

docker build --build-arg MATLAB_RELEASE=R2025b
             --build-arg MATLAB_PRODUCT_LIST="MATLAB Control_System_Toolbox Robust_Control_Toolbox Optimization_Toolbox Symbolic_Math_Toolbox"
             --build-arg MATLAB_INSTALL_LOCATION="/opt/matlab/R2025a"
             -t my_matlab_image_name:tag .

In my case I installed release R2025a and called the image matlab_with_toolboxes_settings:R2025a. If you change settings and want to change the image to preserve them (eg. disable annoying MATLAB Copilot),

Making the host filesystem accessible in the container

I ended up using ACLs for that

setfacl -m u:uid:rwx /path/to/matlab/projects

Where uid is the UID of the matlab user inside the docker container. Admittedly with this, new files are created as the matlab user and the host user will probably have permission denied to them. I’ll figure it out.

I also found this GitHub issue, but I wasn’t able to make it work in a decent. The only idea that comes to is to periodically just run a chown youruser:youruser of files created by the docker container. If anyone reading has a better idea, shoot me an email at the address in the footer.

Licensing

Online licensing

With online licensing, you have to login with your credentials everytime you start the container.

Network licensing with .lic file

Alternatevely, you can use a license (.lic) file. Point MATLAB to your license file using the MLM_LICENSE_FILE environment variable

If you’re a student like me or working for an organization, you’ll have to ask whoever manages the licenses for your organization. It took me a month to get a license, and at first they sent me a license for R2023a. After some back and forth I managed to get a license for R2025a. They asked for my mac address, because that’s how MATLAB checks licenses. I foolishly gave the address of both my desktop and my laptop to bind the license, but the docker container will always have a different address. Luckily the address can be spoofed for the docker container

docker-compose-matlab-r2025a.yml 
---

services:
  matlab:
    container_name: matlab_r2025a
    image: matlab_toolboxes_settings:R2025a
    ports:
      - 5901:5901
      - 6080:6080
      - 8888:8888
    volumes:
      - matlab_data:/home/matlab
      - /home/emamaker/:/home/emamaker
    environment:
      - TZ=Europe/Rome
    shm_size: '8gb'
    command: -browser
    networks:
      matlabnetwork:
        mac_address: "your:mac:address:not:my:address"

volumes:
  matlab_data:
networks:
  matlabnetwork:

Oh wait, distrobox is apparently a thing

Oh well.

I started writing this post mid-September and ended up publishing it in late October, stuff gets in the way and I procrastinate writing on this blog, no matter how much I enjoy it. There, something for my therapist I guess. In between starting to write this post and publishing it I had to install CoppeliaSim for some other uni work, which is only packaged for Ubuntu. They do offer docker images, but I wanted something with more seamless integreation between host and container. I remembered distrobox is a thing, and tried using it for the first time in my life. Absolutely wonderful experience. Documentation could be slightly better organized though.

So for MATLAB:

distrobox create --image ubuntu:24.04

Add the --nvidia option if you have a NVIDIA GPU you wanna pass through to the container

Other ubuntu versions are fine, just compare with the docker image of the version of MATLAB you want to run and check corresponding ubuntu versions and dependencies, here. In my case I want to run R2025a.

sudo apt-get install -y $(curl https://raw.githubusercontent.com/mathworks-ref-arch/container-images/refs/heads/main/matlab-deps/r2025a/ubuntu24.04/base-dependencies.txt)

The only downside I noticed for now is that running MATLAB the standard way (even if through distrobox) you cannot use the WebUI like for docker.

Total time to setup this? 5 minutes, I had MATLAB already installed, only had to run it inside the container. Did I mention you can seamlessy passthrough the host filesystem?

There goes a week of my life dabbling with systemd-nspawn, glibc and docker.