mat73

library0.65pypypi✓ verified 84d ago

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.

data serialization

pip install mat73

github ↗package ↗

INSTALL

IMPORT

SIG · MAT73

mat73

datapythonv0.65

Install

3.9s avg

Import

339ms

Disk

105MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.65 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 3.8s

py 3.11

✓ —

✓ 3.8s

py 3.12

✓ —

✓ 3.8s

py 3.13

✓ —

✓ 3.7s

py 3.9

✕ build_error

✓ 4.4s

105MB installed

● package 105MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mat73

✓ import mat73

✗ from mat73 import loadmat

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).

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

Debug

Known issues

breakingVersion 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]

affects: <0.60

breakingVersion 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.

affects: <0.63

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

fix

Use Python >=3.9.

affects: >=0.64

gotchaThe 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.

affects: all

gotchaBy 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.

affects: <=0.64

Errors

Common errors & fixes

KeyError: 'MATLAB_class'

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.

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

File path is incorrect or file does not exist.

fix

Check the file path and ensure the file exists.

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

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.

Upgrade

Version history

0.65latest on PyPI · released Jul 24, 2024

Audit

Dependencies

h5pyrequiredRequired to read HDF5-format .mat files

numpyrequiredData arrays are returned as numpy arrays

scipyoptionalSparse matrices require scipy.sparse

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/skjerns/mat7.3 ↗

packagehttps://pypi.org/project/mat73/ ↗