Access and change variables directly in MAT-files, without loading into memory


m = matfile(filename)
m = matfile(filename,'Writable',isWritable)



m = matfile(filename) creates a MAT-file object, m, connected to the MAT-file named filename. The object allows you to access and change variables directly in a MAT-file, without having to load the variables into memory.

The partial loading and saving that the matfile function provides requires less memory than the load and save commands, which always operate on entire variables.


m = matfile(filename,'Writable',isWritable) enables or disables write access to the file.


collapse all

Load variable topo from the example file, topography.mat.

Open the example MAT-file, topography.mat.

filename = 'topography.mat';
m = matfile(filename);

Read the variable topo from the MAT-file.

topo = m.topo;

MATLAB® loads the entire variable, topo, into the workspace.

Generate a 20-by-20 example array, x, and save it to a MAT-file called myFile.mat.

x = magic(20);

Create a MAT-file object connected to the existing MAT-file named myFile.mat. Enable write access to the MAT-file by setting Writable to true.

m = matfile('myFile.mat','Writable',true);

Generate a 15-by-15 example array, y.

y = magic(15);

Save y to the MAT-file. Specify the variable in the MAT-file using dot notation similar to accessing fields of structure arrays.

m.y = y;

MATLAB® adds a variable named y to the file.

Display all variables stored in the MAT-file, myFile.mat.

  Name       Size            Bytes  Class     Attributes

  x         20x20             3200  double              
  y         15x15             1800  double              

Access specific elements of a MAT-file variable.

Open a new MAT-file, myFile2.mat.

m = matfile('myFile2.mat');

Save a 20-by-20 example array to part of a variable, y, in myFile2.mat. Specify the variable in the MAT-file using dot notation similar to accessing fields of structure arrays.

m.y(81:100,81:100) = magic(20);

MATLAB® inserts the 20-by-20 array into the elements of y specified by the indices (81:100,81:100).

Read a subset of array y into a new workspace variable, z.

z = m.y(85:94,85:94);

MATLAB reads the 10-by-10 subarray specified by the indices (85:94,85:94) from the MAT-file into workspace variable z.

Determine the size of a variable, and then calculate the average of each column.

Open the example MAT-file, stocks.mat.

filename = 'stocks.mat';
m = matfile(filename);

Determine the size of the variable, stocks, in stocks.mat.

[nrows,ncols] = size(m,'stocks');

Compute the average of each column of the variable stocks.

avgs = zeros(1,ncols);
for i = 1:ncols
    avgs(i) = mean(m.stocks(:,i));

Enable write access to the MAT-file, myFile.mat, by setting Writable to true when you open the MAT-file.

filename = 'myFile.mat';
m = matfile(filename,'Writable',true);

Alternatively, set Properties.Writable in a separate step after you open the MAT-file.

m.Properties.Writable = true;

Input Arguments

collapse all

Name of a MAT-file, specified as a character vector. If the file is not in the current folder, filename must include a full or a relative path. If filename does not include an extension, then matfile appends .mat.

If the file does not exist, then matfile creates a Version 7.3 MAT-file on the first assignment to a variable.

matfile only supports efficient partial loading and saving for MAT-files in Version 7.3 format. If you index into a variable in a Version 7 (the current default) or earlier MAT-file, MATLAB® warns and temporarily loads the entire contents of the variable.

Example: 'myFile.mat'

Data Types: char

Write access to the MAT-file, specified as either true or false.

  • true enables saving to the MAT-file. If the file is read only, MATLAB changes the system permissions with the fileattrib function.

  • false disables saving to the MAT-file. MATLAB does not change the system permissions.

The default value is true for new files, and false for existing files.

Data Types: logical

Output Arguments

collapse all

MAT-file object connected to a MAT-file.

Access variables in the MAT-file with dot notation similar to accessing fields of structure arrays:

  • To load part of variable varName from the MAT-file corresponding to m, call:

    loadedData = m.varName(indices);

  • To save part of variable varName to the MAT-file corresponding to m, call:

    m.varName(indices) = dataToSave;

When accessing variables, specify indices for all dimensions. Indices can be a single value, an equally spaced range of increasing values, or a colon (:); for example:



  • matfile does not support linear indexing. You must specify indices for all dimensions.

  • matfile does not support indexing into:

    • Variables of tables

    • Cells of cell arrays

    • Fields of structure arrays

    • User-defined classes

    • Sparse arrays

  • You cannot assign complex values to an indexed portion of a real array.

  • You cannot evaluate function handles using the m output. For example, if your MAT-file contains function handle myfunc, the syntax m.myfunc() attempts to index into the function handle, and does not invoke the function.

  • Efficient partial loading and saving requires Version 7.3 MAT-files. To create a Version 7.3 MAT-file, call the save function with the '-v7.3' option. For example, to convert an existing MAT-file named durer.mat to Version 7.3, call:



  • Using the end keyword as part of an index causes MATLAB to load the entire variable into memory. For very large variables, this load operation results in Out of Memory errors. Rather than using end, determine the extent of a variable, myVar, with the size method, such as:

    sizeMyVar = size(m,'myVar')

Introduced in R2011b