Main Content

MATLAB Arrays as Python Variables

The matlab Python® package provides array classes to represent arrays of MATLAB® numeric types as Python variables so that MATLAB arrays can be passed between Python and MATLAB.

Create MATLAB Arrays in Python

You can create MATLAB numeric arrays in a Python session by calling constructors from the matlab Python package (for example, matlab.double, matlab.int32). The name of the constructor indicates the MATLAB numeric type.

You can use custom types for initializing MATLAB double arrays in Python. The custom type should inherit from the Python Abstract Base Class collections.Sequence to be used as an initializer.

You can pass MATLAB arrays as input arguments to functions called with the MATLAB Engine API for Python. When a MATLAB function returns a numeric array as an output argument, the engine returns the array to Python.

You can initialize the array with an optional initializer input argument that contains numbers. initializer must be a Python sequence type such as a list, tuple, or other sequence type. The optional size input argument sets the array size from a sequence. You can create multidimensional arrays by specifying initializer to contain multiple sequences of numbers, or by specifying size to be multidimensional. You can create a MATLAB array of complex numbers by setting the optional is_complex input argument to True. The matlab package provides the MATLAB array constructors listed in the table.

matlab Class

Constructor Call in Python


matlab.double(initializer=None, size=None, is_complex=False)


matlab.single(initializer=None, size=None, is_complex=False)


matlab.int8(initializer=None, size=None, is_complex=False)


matlab.int16(initializer=None, size=None, is_complex=False)


matlab.int32(initializer=None, size=None, is_complex=False)


matlab.int64(initializer=None, size=None, is_complex=False)


matlab.uint8(initializer=None, size=None, is_complex=False)


matlab.uint16(initializer=None, size=None, is_complex=False)


matlab.uint32(initializer=None, size=None, is_complex=False)


matlab.uint64(initializer=None, size=None, is_complex=False)


matlab.logical(initializer=None, size=None)[c]


No constructor. When a function returns a handle or a value object to a MATLAB object, the engine returns a matlab.object to Python.

[a] In Python 2.7 on Windows, matlab.int64 is converted to int32 in MATLAB. Also, MATLAB cannot return an int64 array to Python.

[b] In Python 2.7 on Windows, matlab.uint64 is converted to uint32 in MATLAB. Also, MATLAB cannot return a uint64 array to Python.

[c] Logicals cannot be made into an array of complex numbers.

When you create an array with N elements, the size is 1-by-N because it is a MATLAB array.

import matlab.engine
A = matlab.int8([1,2,3,4,5])
(1, 5)

The initializer is a Python list containing five numbers. The MATLAB array size is 1-by-5, indicated by the tuple, (1,5).

MATLAB Array Attributes and Methods in Python

All MATLAB arrays created with matlab package constructors have the attributes and methods listed in this table.

Attribute or Method



Size of array returned as a tuple


Reshape array as specified by sequence size

Multidimensional MATLAB Arrays in Python

In Python, you can create multidimensional MATLAB arrays of any numeric type. Use two Python list variables to create a 2-by-5 MATLAB array of doubles.

import matlab.engine
A = matlab.double([[1,2,3,4,5], [6,7,8,9,10]])

The size attribute of A shows that it is a 2-by-5 array.

(2, 5)

Index Into MATLAB Arrays in Python

You can index into MATLAB arrays just as you can index into Python list and tuple variables.

import matlab.engine
A = matlab.int8([1,2,3,4,5])

The size of the MATLAB array is (1,5); therefore, A[0] is [1,2,3,4,5]. Index into the array to get 3.


Python indexing is zero-based. When you access elements of MATLAB arrays in a Python session, use zero-based indexing.

Index into a multidimensional MATLAB array.

A = matlab.double([[1,2,3,4,5], [6,7,8,9,10]])

Slice MATLAB Arrays in Python

You can slice MATLAB arrays the same way you slice Python list and tuple variables.

import matlab.engine
A = matlab.int8([1,2,3,4,5])

You can assign data to a slice. This code shows assignment from a Python list to a slice of an array.

A = matlab.double([[1,2,3,4],[5,6,7,8]]);
A[0] = [10,20,30,40]

You can assign data from another MATLAB array, or from any Python iterable that contains numbers.

You can specify slices for assignment as shown here.

A = matlab.int8([1,2,3,4,5,6,7,8]);
A[0][2:4] = [30,40]
A[0][6:8] = [70,80]


Slicing MATLAB arrays behaves differently from slicing a Python list. Slicing a MATLAB array returns a view instead of a shallow copy.

Given a MATLAB array and a Python list with the same values, assigning a slice results in different results as shown by the following code.

A = matlab.int32([[1,2],[3,4],[5,6]])
L = [[1,2],[3,4],[5,6]]
A[0] = A[0][::-1]
L[0] = L[0][::-1]
[[2, 1], [3, 4], [5, 6]]

Reshape MATLAB Arrays in Python

You can reshape a MATLAB array in Python with the reshape method. Input argument size must be a sequence that preserves the number of elements. Use reshape to change a 1-by-9 MATLAB array to 3-by-3.

import matlab.engine
A = matlab.int8([1,2,3,4,5,6,7,8,9])

Related Topics