hdf5storage

0.2.2 verified Mon Apr 27 auth: no python

Utilities to read/write Python types to/from HDF5 files, including MATLAB v7.3 MAT files. Current version: 0.2.2. Release cadence: irregular.

pip install hdf5storage

Common errors

error ModuleNotFoundError: No module named 'hdf5storage' ↓

cause Library not installed

fix

Run: pip install hdf5storage

error OSError: Unable to open file (file signature not found) ↓

cause File is not HDF5 or v7.3 format

fix

Ensure file is a valid HDF5/v7.3 file. Use h5py or check file header.

error ValueError: Cannot write object of type <class 'numpy.ndarray'> with dtype object ↓

cause savemat cannot handle arrays of Python objects directly

fix

Convert object arrays to supported types (e.g., list, string) or use h5py.

error TypeError: can't write bytes to HDF5 dataset ↓

cause Trying to write bytes without encoding

fix

Convert bytes to string (e.g., .decode()) or use 'h5py' with vlen bytes data type.

Warnings

deprecated The 'hdf5storage' library is in maintenance mode; consider using 'h5py' or 'mat73' for v7.3 files. ↓

fix Migrate to h5py (direct HDF5) or mat73 (MATLAB v7.3 specific).

breaking Python 3.10+ only; drops support for Python <3.10. ↓

fix Use Python 3.10 or later.

gotcha savemat with default options writes HDF5-compatible files but MATLAB may not read nested structures correctly without specifying 'format'. ↓

fix Always pass format='7.3' for MATLAB compatibility.

gotcha String arrays are stored as HDF5 datasets; when reading, returned strings may be bytes. Use encoding='utf-8' in loadmat if needed. ↓

fix Specify encoding explicitly: loadmat('file.mat', encoding='utf-8')

Imports

loadmat

wrong

from scipy.io import loadmat

correct

from hdf5storage import loadmat

scipy.io.loadmat does not support v7.3 files.

savemat

wrong

from scipy.io import savemat

correct

from hdf5storage import savemat

scipy.io.savemat cannot write v7.3 files.

hdf5storage
wrong
```
import hdf5storage as h5s
```
correct
```
import hdf5storage
```
Alias not required but works; correct import is fine.

Quickstart

Write and read a simple dictionary with an array and a string to a MATLAB v7.3 file.

import hdf5storage
import numpy as np
data = {'array': np.array([1,2,3]), 'string': 'hello'}
# Write to v7.3 MAT file
hdf5storage.savemat('example.mat', data, format='7.3')
# Read back
loaded = hdf5storage.loadmat('example.mat')
print(loaded['array'])