Oct2Py: Python to GNU Octave Bridge

Oct2Py allows you to seamlessly call M-files and Octave functions from Python. It manages the Octave session for you, sharing data behind the scenes using MAT files. Usage is as simple as:

>>> import oct2py
>>> oc = oct2py.Oct2Py()
>>> x = oc.zeros(3, 3)
>>> print(x, x.dtype)
[[0. 0. 0.]
 [0. 0. 0.]
 [0. 0. 0.]] float64

To run .m function, you need to explicitly add the path to .m file using:

>>> from oct2py import octave
>>> # to add a folder use:
>>> octave.addpath("/path/to/directory")  # doctest: +SKIP
>>> # to add folder with all subfolder in it use:
>>> octave.addpath(octave.genpath("/path/to/directory"))  # doctest: +SKIP
>>> # to run the .m file :
>>> octave.run("fileName.m")  # doctest: +SKIP

To get the output of .m file after setting the path, use:

>>> import numpy as np
>>> from oct2py import octave
>>> x = np.array([[1, 2], [3, 4]], dtype=float)
>>> # use nout='max_nout' to automatically choose max possible nout
>>> octave.addpath("./example")  # doctest: +SKIP
>>> out, oclass = octave.roundtrip(x, nout=2)  # doctest: +SKIP
>>> import pprint  # doctest: +SKIP
>>> pprint.pprint([x, x.dtype, out, oclass, out.dtype])  # doctest: +SKIP
[array([[1., 2.],
        [3., 4.]]),
    dtype('float64'),
    array([[1., 2.],
        [3., 4.]]),
    'double',
    dtype('<f8')]

If you want to run legacy m-files, do not have MATLAB®, and do not fully trust a code translator, this is your library.

Features

Supports all Octave datatypes and most Python datatypes and Numpy dtypes.
Provides OctaveMagic for IPython, including inline plotting in notebooks.
Supports cell arrays and structs/struct arrays with arbitrary nesting.
Supports sparse matrices.
Builds methods on the fly linked to Octave commands (e.g. zeros above).
Thread-safety: each Oct2Py object uses an independent Octave session.
Can be used as a context manager.
Supports Unicode characters.
Supports logging of session commands.
Optional timeout command parameter to prevent runaway Octave sessions.

Supported Python and dependency versions

This project follows SPEC 0 for minimum supported Python and dependency versions.

Installation

You must have GNU Octave installed and in your PATH environment variable. Alternatively, you can set an OCTAVE_EXECUTABLE or OCTAVE environment variable that points to octave executable itself.

You must have the Numpy and Scipy libraries for Python installed. See the installation instructions for more details.

Once the dependencies have been installed, run:

$ pip install oct2py

If using conda, it is available on conda-forge:

$ conda install -c conda-forge oct2py

Documentation

Documentation is available online.

For version information, see the Changelog.

JupyterHub with Qt Support

To enable Octave's Qt graphics toolkit in a JupyterHub environment (or any headless server), you need a virtual display. Install the required system packages:

apt-get install -y octave libglu1 xvfb texinfo fonts-freefont-otf ghostscript

Start Xvfb before launching JupyterHub (or in a server startup script):

Xvfb :99 -screen 0 1024x768x24 &
export DISPLAY=:99

Then configure oct2py to use the Qt backend in your notebook or script:

from oct2py import octave
octave.eval("graphics_toolkit qt")

Alternatively, set OCTAVE_EXECUTABLE to run Octave under xvfb-run:

export OCTAVE_EXECUTABLE="xvfb-run octave"

For Binder-based deployments, the binder/ directory in this repository contains an apt.txt listing required packages and a start script that launches Xvfb and exports DISPLAY before the Jupyter server starts, enabling Qt graphics out of the box.

Release files for oct2py 6.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oct2py 6.1.1
File	Size	Uploaded
oct2py-6.1.1.tar.gz	77.6 kB	Aug 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for oct2py 6.1.1
File	Interpreter	ABI	Platform	Reset
oct2py-6.1.1-py3-none-any.whl 43.2 kB Aug 23, 2026	Python 3	none	any	Details

Total release size: 120.9 kB

Release files / oct2py-6.1.1.tar.gz

Download URL	oct2py-6.1.1.tar.gz
Size	77.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`a7badb0294be3ab1cf3caf646049e70ae2fbff0805b5cd2b06d7b09cf5378695`
BLAKE2b-256 checksum How to use checksums	`9083792fce2ea65ea7d2c480620bb461cf59230244ded4d2853ac3d5b87257a0`
Upload date	Aug 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / oct2py-6.1.1-py3-none-any.whl

Download URL	oct2py-6.1.1-py3-none-any.whl
Size	43.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`58751fc071f67ec5f5836922bfd88dc062bd5ee3e120f2730f09575bf95b1449`
BLAKE2b-256 checksum How to use checksums	`a3a4e2b2b181b4d19d345cc4aa7f753248d7308432f9e00289eb9d794702af2d`
Upload date	Aug 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`