mat73

0.65 verified Fri May 01 auth: no python

Load MATLAB .mat v7.3 files into Python native data types via h5py. Version 0.65, stable release with support for sparse matrices, cell arrays, and selective variable loading.

pip install mat73

Common errors

error KeyError: 'MATLAB_class' ↓

cause The file is not a valid MATLAB v7.3 file (e.g., it's an older format).

fix

Use scipy.io.loadmat for legacy .mat files, or convert the file to v7.3 in MATLAB.

error OSError: Unable to open file (unable to open file: name = 'file.mat', errno = 2, error message = 'No such file or directory') ↓

cause File path is incorrect or file does not exist.

fix

Check the file path and ensure the file exists.

error TypeError: expected str, bytes or os.PathLike object, not ... ↓

cause loadmat expects a file path string or file-like object; passing an unsupported type.

fix

Pass a string path or a file-like object opened in binary mode.

Warnings

breaking Version 0.60 removed automatic null-character stripping from strings; strings now keep null characters. ↓

fix Upgrade to >=0.60 and manually strip nulls if needed: s.split('\x00')[0]

breaking Version 0.63 fixed sparse matrix bug #51; previously sparse loading could crash or produce incorrect results. ↓

fix Upgrade to >=0.63 for correct sparse matrix support.

deprecated Python 3.8 support is dropped as of version 0.64; no warning emitted but installation may fail. ↓

fix Use Python >=3.9.

gotcha The library only supports MATLAB v7.3 files (HDF5-based). It will silently fail or produce garbage on older .mat formats. ↓

fix Verify your .mat file is v7.3 by checking if h5py can open it, or use scipy.io.loadmat for older formats.

gotcha By default, mat73.loadmat squeezes singleton dimensions of arrays. This can remove dimensions unintentionally. ↓

fix In >=0.65, use mat73.loadmat('file.mat', squeeze=False) to preserve dimensions.

Imports

mat73
wrong
```
from mat73 import loadmat
```
correct
```
import mat73
```
Common mistake: mat73 does not expose loadmat as a top-level function; use mat73.loadmat() or from mat73 import loadmat (which works but is less conventional).

Quickstart

Load a .mat v7.3 file and inspect variable names.

import mat73
import numpy as np

data = mat73.loadmat('test.mat')
print(data.keys()) # list variables