mat-io

0.7.1 verified Mon Apr 27 auth: no python

A modern Python library for reading and writing MATLAB .mat files (v7 and v7.3 formats) with native support for MATLAB datatypes like table, string, datetime, struct, and cell. Version 0.7.1 runs on Python ≥3.11. Development is active, with regular releases.

pip install mat-io

Common errors

error ModuleNotFoundError: No module named 'matio' ↓

cause Installed package is 'mat-io' (hyphen), but imported as 'matio' (no hyphen). The package name on PyPI uses hyphen, but the import uses underscore? Actually the import is 'matio' as per docs.

fix

pip install mat-io, then import matio.

error matio.MatioError: Unsupported MATLAB version ↓

cause Attempting to read a .mat file from an unsupported older MATLAB version or a corrupt file.

fix

Resave the .mat file in MATLAB using v7 or v7.3 format.

error TypeError: cannot convert numpy array to MATLAB array ↓

cause Attempting to write unsupported data types (e.g., object arrays, structured arrays with non-numeric fields).

fix

Convert data to supported types: numeric, string, cell, struct.

Warnings

breaking Python >=3.11 required; no support for older Python versions. ↓

fix Upgrade Python to 3.11 or later.

gotcha MATLAB string arrays containing NaN are not supported in write operations (v0.5.2+). ↓

fix Use missing strings or convert NaN to empty strings before saving.

deprecated The old scipy.io.loadmat is not a drop-in replacement; mat-io has different API and handles newer MATLAB types. ↓

fix Use mat-io's MatFileReader for proper table/string support.

Imports

MatFileReader

wrong

from matio.reader import MatFileReader

correct

from matio import MatFileReader

Public API is at top-level

MatFileWriter

wrong

from matio.writer import MatFileWriter

correct

from matio import MatFileWriter

Public API is at top-level

MatObject
```
from matio import MatObject
```

Quickstart

Load a .mat file and print variable names.

from matio import MatFileReader
import os

filename = 'example.mat'
if os.path.exists(filename):
    reader = MatFileReader(filename)
    data = reader.read()
    print(data.keys())
else:
    print('File not found.')