Main Content

Resolve “Out of Memory” Errors

Issue

When your code operates on large amounts of data or does not use memory efficiently, MATLAB® might produce an error in response to an unreasonable array size, or it might run out of memory. MATLAB has built-in protection against creating arrays that are too large. For example, this code results in an error, because MATLAB cannot create an array with the requested number of elements.

A = rand(1e9);

Requested array exceeds the maximum possible variable size.

By default, MATLAB can use up to 100% of the RAM (not including virtual memory) of your computer to allocate memory for arrays, and if an array size would exceed that threshold, then MATLAB produces an error. For example, this code attempts to create an array whose size exceeds the maximum array size limit.

B = rand(1e6);

Requested 1000000x1000000 (7450.6GB) array exceeds maximum array size preference (63.7GB). This might cause MATLAB to become
unresponsive.

If you turn off the array size limit in MATLAB Workspace Preferences, attempting to create an unreasonably large array might cause MATLAB to run out of memory, or it might make MATLAB or even your computer unresponsive due to excessive memory paging (that is, moving memory pages between RAM and disk).

B = rand(1e6);

Out of memory.

Possible Solutions

No matter how you run into memory limits, MATLAB provides several solutions depending on your situation and goals. For example, you can improve the way your code uses memory, leverage specialized data structures such as datastores and tall arrays, take advantage of pooled resources within a computing cluster, or make adjustments to your settings and preferences.

Note

The solutions presented here are specific to MATLAB. To optimize system-wide memory performance, consider adding more physical memory (RAM) to your computer or making adjustments at the operating system level.

Clear Variables When No Longer Needed

Make it a practice to clear variables when they are no longer needed. To clear items from memory, use the clear function.

BeforeAfter
A = rand(1e4);
disp(max(A,[],"all"))
B = rand(1e4);

A = rand(1e4);
disp(max(A,[],"all"))
clear A
B = rand(1e4);

For more information, see Strategies for Efficient Use of Memory.

Use Appropriate Data Storage

Memory requirements differ for MATLAB data types. You might be able to reduce the amount of memory used by your code by using the appropriate data type and storage. For more information about the solutions in this section, see Strategies for Efficient Use of Memory.

Use the Appropriate Numeric Class.  The numeric class you should use depends on your intended actions. In MATLAB, double is the default numeric data type and provides sufficient precision for most computational tasks:

  • If you want to perform complicated math such as linear algebra, use floating-point numbers in either double-precision (double) or single-precision (single) format. Numbers of type single require less memory than numbers of type double, but are also represented to less precision.

  • If you just need to carry out simple arithmetic and you represent the original data as integers, use the integer classes in MATLAB.

Class (Data Type)BytesSupported Operations
single4Most math
double8All math
logical1Logical/conditional operations
int8, uint81Arithmetic and some simple functions
int16, uint162Arithmetic and some simple functions
int32, uint324Arithmetic and some simple functions
int64, uint648Arithmetic and some simple functions

Reduce the Amount of Overhead When Storing Data.  When you create a numeric or character array, MATLAB allocates a block of memory to store the array data. MATLAB also stores information about the array data, such as its class and dimensions, in a small, separate block of memory called a header. Because simple numeric and character arrays have the least overhead, use them whenever possible. Use other data structures only for data that is too complex to store in a simple array.

For structures and cell arrays, MATLAB creates a header not only for the array, but also for each field of the structure or each cell of the cell array. Therefore, the amount of memory required to store a structure or cell array depends not only on how much data it holds, but also on how it is constructed. As a result, cell arrays with many small elements or structures with many fields containing little content have large overhead and should be avoided.

BeforeAfter
% S has 15,000 fields (3 fields per array element)
for i = 1:100
    for j = 1:50
        S(i,j).R = 0;  % Each field contains a numeric scalar
        S(i,j).G = 0;
        S(i,j).B = 0;
    end
end
 
% S has 3 fields 
S.R = zeros(100,50);  % Each field contains a numeric array
S.G = zeros(100,50);
S.B = zeros(100,50);

Make Arrays Sparse When Possible.  A good practice is to store matrices with few nonzero elements using sparse storage. When a full matrix has a small number of nonzero elements, converting the matrix to sparse storage typically improves memory usage and code execution time. MATLAB has several functions that support sparse storage. For example, you can use the speye function to create a sparse identity matrix.

BeforeAfter
I = eye(1000);
 
I = speye(1000);

Import Data Using the Appropriate MATLAB Class.  When reading data from a binary file with fread, a common mistake is to specify only the class of the data in the file and not the class of the data MATLAB uses once it is in the workspace. If you do not specify the class of the data in memory, MATLAB uses double even if you read 8-bit values.

BeforeAfter
fileID = fopen("large_file_of_uint8s.bin","r"); 
A = fread(fileID,1e3,"uint8"); 
fileID = fopen("large_file_of_uint8s.bin","r"); 
A = fread(fileID,1e3,"uint8=>uint8");

Avoid Unnecessary Copies of Data

To improve memory usage and execution speed, make sure your code does not result in unnecessary copies of data. For more information about the solutions in this section, see Avoid Unnecessary Copies of Data and Strategies for Efficient Use of Memory.

Avoid Creating Temporary Arrays.  Avoid creating temporary arrays when they are not necessary. For example, instead of creating an array of zeros as a temporary variable and then passing that variable to a function, use one command to do both operations.

BeforeAfter
A = zeros(1e6,1);
As = single(A);
 
As = zeros(1e6,1,"single");

Preallocate Memory.  When you work with large data sets, repeatedly resizing arrays might cause your program to run out of memory. If you expand an array beyond the available contiguous memory of its original location, MATLAB must make a copy of the array and move the copy into a memory block with sufficient space. During this process, two copies of the original array exist in memory. You can improve the memory usage and code execution time by preallocating the maximum amount of space required for the array. For more information, see Preallocation.

BeforeAfter
x = 0;
for k = 2:1000000
   x(k) = x(k-1) + 5;
end
 
x = zeros(1,1000000);
for k = 2:1000000
   x(k) = x(k-1) + 5;
end

Use Nested Functions to Pass Fewer Arguments.  When calling a function, MATLAB typically makes a temporary copy of the variable in the caller's workspace if the function modifies its value. MATLAB applies various techniques to avoid making unnecessary copies, but avoiding a temporary copy of an input variable is not always possible.

One way to avoid temporary copies in function calls is to use nested functions. A nested function shares the workspace of all outer functions, so you do not need to pass a copy of variables in the function call. For more information, see Nested Functions.

Load Only as Much Data as You Need

One way to fix memory issues is to import into MATLAB only as much of a large data set as you need for the problem you are trying to solve. Data set size is not usually a problem when importing from sources such as a database, where you can explicitly search for elements matching a query. But it is a common problem with loading large flat text or binary files.

The datastore function lets you work with large data sets incrementally. Datastores are useful any time you want to load only some portions of a data set into memory at a time.

To create a datastore, provide the name of a file or a directory containing a collection of files with similar formatting. For example, with a single file, use the following.

ds = datastore("path/to/file.csv");
Or with a collection of files in a folder, use the following.
ds = datastore("path/to/folder/");
You also can use the wildcard character * to select all files of a specific type.
ds = datastore("path/to/*.csv");
Datastores support a wide variety of file formats (tabular data, images, spreadsheets, and so on). For more information, see Select Datastore for File Format or Application.

Aside from datastores, MATLAB also has several other functions to load parts of files. This table summarizes the functions by the type of files they operate on.

File TypePartial Loading
MAT-file

Load part of a variable by indexing into an object that you create with the matfile function. For more information, see Save and Load Parts of Variables in MAT-Files.

Text

Use the textscan function to access parts of a large text file by reading only the selected columns and rows. If you specify the number of rows or a repeat format number with textscan, MATLAB calculates the exact amount of memory required beforehand.

Binary

You can use low-level binary file I/O functions, such as fread, to access parts of any file that has a known format. For binary files of an unknown format, try using memory mapping with the memmapfile function.

Image, Audio, Video, and HDF

Many of the MATLAB functions that support loading from these types of files allow you to select portions of the data to read. For details, see the function reference pages listed in Supported File Formats for Import and Export.

Use Tall Arrays

Tall arrays help you work with data sets that are too large to fit in memory. MATLAB works with small blocks of the data at a time, automatically handling all of the data chunking and processing in the background. You can use tall arrays in two primary ways:

  • If you have a large array that fits in memory, but you run out of memory when you try to perform calculations, you can cast the array to a tall array.

    t = tall(A);
    This approach lets you work with large arrays that can fit in memory, but that consume too much memory to allow for copies of the data during calculations. For example, if you have 8 GB of RAM and a 5 GB matrix, casting the matrix to a tall array enables you to perform calculations on the matrix without running out of memory. For an example of this usage, see tall.

  • If you have file- or folder-based data, you can create a datastore and then create a tall array on top of the datastore.

    ds = datastore("path/to/file.csv");
t = tall(ds);
    This approach gives you the full power of tall arrays in MATLAB. The data can have any number of rows and MATLAB does not run out of memory. And because datastore works with both local and remote data locations, the data you work with does not need to be on the computer you use to analyze it. See Work with Remote Data for more information.

To learn more about tall arrays, see Tall Arrays for Out-of-Memory Data.

Use Memory of Multiple Machines

If you have a cluster of computers, you can use distributed arrays (requires Parallel Computing Toolbox™) to perform calculations using the combined memory of all the machines in the cluster. Depending on how your data fits in memory, different ways to partition data among workers of a parallel pool exist. For more information, see Distributing Arrays to Parallel Workers (Parallel Computing Toolbox).

Adjust Settings and Preferences

Generally, rewriting code is the most effective way to improve memory performance. However, if you cannot make changes to your code, these solutions might provide it with the required amount of memory.

Start MATLAB Without Java Virtual Machine or Decrease the Java Heap Size.  If you either start MATLAB without the Java® Virtual Machine (JVM®) software or decrease the Java heap size, you can increase the available workspace memory. To start MATLAB without JVM, use the command-line option -nojvm. For information on how to decrease the Java heap size, see Java Heap Memory Preferences.

Using -nojvm comes with a penalty in that you lose several features that rely on JVM, such as the desktop tools and graphics. Starting MATLAB with the -nodesktop option does not save any substantial amount of memory.

Adjust the Array Size Limit.  If you face an error stating that the array size exceeds the maximum array size preference, you can adjust this array size limit in MATLAB. For information on adjusting the array size limit, see Workspace and Variable Preferences. This solution is helpful only if the array you want to create exceeds the current maximum array size limit but is not too large to fit in memory. Even if you turn off the array size limit, attempting to create an unreasonably large array might cause MATLAB to run out of memory, or it might make MATLAB or even your computer unresponsive due to excessive memory paging.

See Also

| | |

Related Topics