Matlab-based IPython notebooks

21 February 2018, update: the new JupyterLab was just released, and according to this tweet is really easy to integrate with Matlab. Probably worth checking out instead of the reasonably outdated instructions below!

I really like Python’s philosophy, but over the last years I haven’t been able to switch the code for my research from Matlab. At this point, the transition costs are too high for me, but it’s a move I have planned for some point in the future.

Now, Python has the awesome Jupyter (formerly IPyton notebook) feature, that allows for comments, code, and most importantly graphical output (i.e. figures you’ve just generated) to be shown in one document. This is a great way to share and explain the code you’re writing, since the reader immediately sees how output is generated without having to run all the analyses themselves.

Matlab has a Publish function that attempts to do something similar, and outputs HTML files containing both code and figures. However, there are a few drawbacks: it uses its own Markup text layout language, and GitHub (where I intend to host my notebooks) does not natively render html.

Luckily, some awesome people have made it really easy to generate IPython notebooks using Matlab, that are super easy to share or host on GitHub. Here’s the step-by-step guide:

    1. Download and install Anaconda Restart Terminal. Or, if you’d prefer to not get the full Anaconda software, check out this post.
    2. In terminal, type
      pip install pymatbridge
      pip install matlab_kernel
      python -m matlab_kernel install
    3. Point the kernel to your version of Matlab. I added
      export MATLAB_EXECUTABLE=/Applications/ to my .bash_profile file. To do this from Terminal, type echo “export MATLAB_EXECUTABLE=/Applications/” >> ~/.bash_profile. Of course, make sure the location and version of Matlab match yours.
    4. Restart terminal or load .bash_profile. Type ipython notebook in Terminal. Your browser will open a Jupyter window, where on the right hand side you can go to New -> Notebooks -> Matlab.
    5. You’re now ready to run your notebook! Simply write or copy a block of code from matlab, and click Run. The figures will automatically appear when you are calling any plotting function. When you push your Notebook.ipynb file to GitHub, it will automatically render the layout and figures. You can also download the whole notebook to HTML which can be viewed in any web browser.

    See here for an example notebook, analysing some pupillometry data in Matlab. Here’s a screenshot of a notebook on signal detection theory:

    Screen Shot 2015-11-12 at 14.54.50

    This code works on a Mac OS X El Capitan, and requires some familiarity with Terminal.

    31 thoughts on “Matlab-based IPython notebooks

    1. Hey! Thanks for this post. One suggestion: In point 3, it’s very easy to miss the “export” command. It’ll be probably helpful if you reformat the line.

    2. Does this work also when only the Matlab runtime (MCR) is installed? Think of making jupyter notebooks available for students who can’t afford to buy a Matlab license. Thanks.

      1. Once a Jupyter notebook has been created it can be viewed by anybody through a web browser – much like an html file with figures included (eg, from the developer of the matlab_kernel, To generate the notebooks, however, you very probably need to point the kernel to a full version of Matlab. Note that I’m not the developer of any of these tools, so you might want look up the original source code for more specifics.

    3. That was quick 😉 Thanks.
      Yeah I am aware about the portability. I was thinking to use it with the grading function of Jupyter…give students task to fulfill. And if they would need a full Matlab install on their machines that would be a major show stopper. Thanks again.

      1. I see! I didn’t know about the grading function but it looks very useful indeed. I’m afraid I can’t really help you, but if you manage to get this to work I’d be very happy to know.

    4. everything installed fine. tried creating a new notebook, but “Notebooks” under “New” is grayed out. Halp.

      1. There is one thing missing from the instructions above to get this working in my system, perhaps that helps to you too.

        Just add “python -m matlab_kernel.install” after the installation of matlab kernel (pip install matlab_kernel)

        I found that info from the instructions on how to install matlab_kernel:

        Hope it helps!

      1. I just followed the instructions on Windows. The only difference is how to point the kernel to Matlab. In Windows you can do it under Control Panel > System. I was able to create a Matlab notebook. So far it’s writing “Connected” every few seconds. I tried to run a command but it’s taken 10 minutes now (usually it takes 30 seconds). I’m giving it some more time 🙂 If it works I’ll write a blog post on it.

        1. Would you be willing to say a little more about what you did under Control Panel > System to get this to work? I am not sure how to go about translating the final step for pointing the kernel into windows terms.

        2. Hi Vera,
          if you go to the control panel, type “Environment” into the search bar, then the link “Edit the system environment variables” should appear. Click on it and enter username and password for an admin account (can be your user). Click on environment variables and click “New…”. Give it the name “MATLAB_EXECUTABLE” and enter the path to your matlab. This is “C:\Program Files\MATLAB\R2014a\bin\matlab.exe” in my case. (you have to use quotes!)
          Does this work for you?
          Best regards,

    5. I followed the instruction, but it did not work for me. I tried to run a cell of Matlab code but nothing happens, although the current kernel was set as Matlab. Please help!! I am using a Mac OS X El Capitan.

      1. @ Oanh Vu I had the same problem (spent 2 days trying commands in the Terminal). The tricky part is pointing your version of Matlab (you check the version at “Macintosh HD”/Applications/MATLAB_R2015a or perhaps 20XXb or something).

        once you know what version of MATLAB you can automatically edit *.bash_profile*

        by pasting:

        echo “export MATLAB_EXECUTABLE=/Applications/” >> ~/.bash_profile

        into the terminal
        then restart the terminal

    6. That’s real cool, and yes, sometimes do see my self using Jupyter notebooks for some old Matlab code.
      My own experience through (after failing to port some old codebase Matlab->Python) – I was able to port my Matlab libraries to Julia language, the code is clearer, faster, and supports Jupyter notebooks. I’d give it a try (the example above is easily recoded there [ using eg: ]

    Leave a Reply

    Fill in your details below or click an icon to log in: Logo

    You are commenting using your account. Log Out /  Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out /  Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out /  Change )

    Connecting to %s