Main Content

Pass MATLAB Data to Python

When calling a Python® function, MATLAB® converts MATLAB data into types that best represent the data in the Python language. For information about using Python data in MATLAB, see Handle Data Returned from Python Function.

MATLAB Type to Python Scalar Type Mapping

MATLAB Input Argument Type —
Scalar Values Only

Resulting Python py. Type

Examples

double (real)
single (real)

float (default) or int

Use Python Numeric Variables in MATLAB

By default, MATLAB converts type double to Python float.
For integer values based on Python type hints, MATLAB can convert type double to Python int.

double (complex)
single (complex)

complex

 
z = complex(1,2);
py.cmath.polar(z)
ans = 
  Python tuple with no properties.

    (2.23606797749979, 1.1071487177940904)

int8
uint8
int16
uint16
int32

int

 

uint32
int64
uint64

int

 

NaN

float("nan")

 

Inf

float("inf")

 

string scalar
char vector

str

Use Python str Variables in MATLAB

<missing> value in string

None

 
py.list({string(missing),'Value'})
ans = 
  Python list with no properties.

    [None, 'Value']

logical

bool

 

dictionary

dict

Use Python Dictionaries in MATLAB

struct

dict

Use Python Dictionaries in MATLAB
tablepy.pandas.DataFrameUse Python Pandas DataFrames in MATLAB
timetablepy.pandas.DataFrameUse Python Pandas DataFrames in MATLAB
datetime

py.datetime.datetime

Use MATLAB datetime Types with Python
duration

py.datetime.timedelta

Use MATLAB duration Types with Python

Python object — py.type

type

 

function handle @py.module.function, to Python functions only

module.function

Pass Python Function to Python map Function

Pass Vectors to Python

MATLAB Input Argument Type —
1-by-N Vector

Resulting Python Type

double (real)

array.array('d')

single (real)

array.array('f')

int8 (real)

array.array('b')

uint8 (real)

array.array('B')

int16 (real)

array.array('h')

uint16 (real)

array.array('H')

int32 (real)

array.array('i')

uint32 (real)

array.array('I')

int64 (real)

array.array('q')

uint64 (real)

array.array('Q')

double (complex)
single (complex)

memoryview

logical

memoryview

char vector
string scalar

str

cell vector

tuple

Pass Matrices and Multidimensional Arrays to Python

The Python language provides a protocol for accessing memory buffers like the data stored in a MATLAB array. MATLAB implements this Python buffer protocol for MATLAB arrays so that you can read MATLAB arrays directly from Python code, running in the same process as MATLAB, without copying data.

Many Python functions directly use the MATLAB array from Python without converting it to a native Python type. Some functions might require a specific type, such as numpy.ndarray, or might modify data in the array. These functions might accept the MATLAB array and copy the data into the required type. Other functions might display an error if you do not pass the required type. To pass data to these functions, first create the required Python type from the MATLAB data, then pass it to the Python function. For example, to create array p to pass to a Python function that requires data of type numpy.array, type:

p = py.numpy.array(magic(3))
p = 

  Python ndarray:

     8     1     6
     3     5     7
     4     9     2

    Use details function to view the properties of the Python object.

    Use double function to convert to a MATLAB array.

MATLAB sparse arrays are not supported in Python. See Unsupported MATLAB Types.

Troubleshooting Argument Errors

If a Python function expects a specific Python multidimensional array type such as numpy.ndarray, then MATLAB displays a message with tips about how to proceed. If the problem might be due to passing a matrix or a multidimensional array as an argument, then do the following.

  1. Check the documentation for the Python function and find out the expected type for the argument.

  2. Create a Python object of that type in MATLAB and pass that to the Python function.

For example, suppose that the following code returns an error.

a = [1 2; 3 4];
py.pyfunc(a)

If the documentation of pyfunc specifies that the expected type is numpy.ndarray, then try this conversion:

py.pyfunc(numpy.ndarray(a))

If the error persists, then determine the root cause by checking for additional information in the Python exception.

Unsupported MATLAB Types

These MATLAB types are not supported in Python.

  • Multidimensional char or cell arrays

  • Sparse arrays

  • struct arrays

  • categorical types

  • containers.Map types

  • MATLAB objects

  • matlab.metadata.Class (py.class)

Related Examples

More About