MATLAB Community

MATLAB, community & more

Controlling the Java Heap Size 12

Posted by Michael Katz,

When you create a Java object from MATLAB, that object will live in the Java heap, whereas workspace variables will go into MATLAB’s main memory. The Java heap space is also shared with MATLAB user interface components, such as figures, the Desktop, and the Editor. You can see in the following example that no size is listed for the java variable, ja:

free = java.lang.Runtime.getRuntime.freeMemory
ja(1,1,1) = java.lang.Double(23);
free = java.lang.Runtime.getRuntime.freeMemory
free =


  Name      Size            Bytes  Class                 Attributes

  free      1x1                 8  double                          
  ja        1x1                    java.lang.Double[]              

free =


Total amount of memory available for Java is set when MATLAB starts up and cannot be changed at run time. However this value can be queried with the following command:

max = java.lang.Runtime.getRuntime.maxMemory
max =


I wrote awhile ago about how MATLAB manages its Java memory (including the distinction between the maximum heap size, the current heap size, and free memory). At the time (MATLAB R2009a) the only way to change the maximum value by creating a java.opts file in your startup directory to set this value with a JVM flag. In the instances where you need more available memory (generally when dealing with Java-intensive toolboxes or managing a lot of really large files), we’ve made it easier in MATLAB R2010a to set this value with panel in the Preferences: File -> Preferences -> General -> Java Heap Memory. No longer do you have to worry about setting JVM flag directly.

MATLAB Java Heap Size Preferences

If you should run out of Java memory, just come to this dialog, and move the slider to the right. You’ll then have to restart MATLAB for the settings to take effect. Note that the default and maximum heap settings vary by platform and processor word-size.

I don’t know the demographics of my readers (beyond the general MATLAB user), but if you’re of my generation, maybe you remember Fraggle Rock? Whenever I hear the word heap, I can’t help but think of the show’s Trash Heap. If you’ve got two minutes to waste, here’s a YouTube video of said Heap.


Comments are closed.

12 CommentsOldest to Newest

Yair Altman replied on : 1 of 12

Mike – is it possible for Matlab to report the size of Java objects, as it does for regular Matlab objects? Currently, whos returns zero size for Java objects. Especially for large Java objects (where the heap size is important), this is very useful information to know.

Unfortunately, Java does not provide a run-time way to know an object’s size: Several algorithms circulate online, but they are all estimates, and some take a long time to evaluate. If Matlab would simply text the free memory before and after Java object construction/update, a very fast size estimate could be reported.

Thanks in advance,
– Yair

Ted Tower replied on : 2 of 12

Thanks for this insight. I dived into Java for a project a year ago, but didn’t have the time to invest into how to get my Java and MATLAB code to play nice. Tidbits like this will help!

Jonas replied on : 3 of 12

Nice feature. I have a few questions, though:
– If both set the heap size and add a java.opts file, which one is being considered?
– In my Matlab installation, the java heap size is limited to 256 MB of RAM in the GUI. Why? I’d like to be able to set it to 1GB to handle large numbers of java objects and use (most of) the other 7GB of RAM to store Matlab variables.

Mike replied on : 4 of 12


It’s not just a matter of evaluating the free memory before and after, because each java command from MATLAB is not an atomic evaluation. There are objects created for the typing events, callbacks thrown, and JMI events that happen as well. Also garbage collection could be run between two evaluations of the free memory, making it seem like a new object had negative size! :) If you have a use case for knowing the size of a Java object, I’d be happy to pass that along to our infrastructure team.

Let us know if you have topics you’d like to see.

I believe The java.opts file in your startup directory will take precedence over the settings, but I am double checking. We limit the size of the slider to prevent people from allocating too much memory and hosing their system. You can always specify a higher value with -Xmx in a java.opts file.

Yair Altman replied on : 5 of 12

Thanks Mike. You are of course correct with all your points. It is simply frustrating for me not to be able to profile Java memory usage as easily as Matlab memory or CPU usage.

My most relevant use-case is trying to debug a GUI-laden application that keeps running into the Java heap memory barrier. It also happens when I use external Java classes that map large data sets. There can be many different causes: memory leaks, unnecessary leftover objects, too many concurrently-active components, inefficient memory hibernation etc.

It is very difficult to debug such issues in today’s Matlab. I usually depend on gut feeling, trial-and-error, or (when all else fails) JDK tools. This takes much more time and is less effective to debug than for Matlab code.

I’m not asking for a full-blown heap-walker – a simple reliable report of object sizes will be most appreciated. And yes, I do appreciate that my request is anything but simple – not because of Matlab, but because of Java design limitations (now that James Gosling left Sun, maybe you can hire him… just kiddin’…).


Yair Altman replied on : 6 of 12

Followup on the Java object size issue: please take a look at Classmexer ( It uses JVM instrumentation (available on JVM 1.5+) to report object sizes. Notwithstanding all the correct reservations you have raised above, I believe that JVM’s own instrumentation gives the closest possible estimate of the actual object size.

I am using classmexer successfully in Matlab, after simply adding classmexer.jar to the classpath and the relevant -javaagent switch to my java.opts.

While deep-scanning takes some time to execute and cannot therefore be placed in the Workspace table’s Cell-renderer, a simple asynchronous thread that would periodically deep-scan Java objects and refresh the table should be relatively easy to implement.

Amro replied on : 7 of 12

Thanks mike for the informative post!

I have a program which runs many fixed point MEX functions, after running the code around 10K times I’d get the java heap space error. Although increasing heap space may help, I feel it just makes the simulation run for another 10K runs before running out again.

It seems that java is somehow accumulating memory usage and not clearing variables with each new call to my functions. Would you be able to guide me in the right direction?

Mike replied on : 8 of 12

Are your MEX functions making java calls? If so, they may not be garbage collected if you’re dangling pointers. In MATLAB you can leak Java objects by attaching them to handles and then not clearing them properly, I forget the exact sequence, it’s been awhile since I’ve had to deal with that. You can also try “clear java” in that case. If that doesn’t work, technical support might be able to help you.

Amro replied on : 9 of 12

I’m not specifically making java calls but I am creating fi objects within my mex files (or collecting fimath info from inputs).

I’ll definetly try the clear java option and check technical support if this persists further.

Thanks for your help.

Christopher Barber replied on : 10 of 12

I am running R2012a on 64-bit Windows 7 and it appears to be ignoring my java.opts file. The only way I have found to increase the max size beyond the 1024MB limit of the preferences dialog is to hack the matlab.prf file directly.

Christopher Barber replied on : 11 of 12

My issue with my java.opts file was that it needs to be in the starting current directory when matlab is started, which is not necessarily the same as the bin/ directory on Windows. I tweaked my startup shortcut to explicitly specify a starting directory.

Michael Katz replied on : 12 of 12


Yes that is how it’s supposed to be done. It’s a bit of advanced maneuver, which is why we don’t make it easy. I’ll let the team know about upping the slider limit.