skills/matlab/references/octave-compatibility.md
GNU Octave 11.3.0 is the current stable release as of 2026-07-23 (released 2026-06-01). It is free software under GPLv3+. MATLAB R2026a is proprietary. Do not describe Octave as MATLAB, a licensed toolbox substitute, or a drop-in guarantee.
Use three labels:
Source resemblance is not enough. Compare outputs with scientific tolerances, edge cases, warnings, graphics, performance, and file round trips.
Octave 11 introduced improved classdef support, broadcasting for sparse,
diagonal, and permutation matrices, more MATLAB-compatible nanflag/vecdim
behavior, and many function/performance changes. It is still not fully
compatible. NEWS-11 also records behavior changes that can break older Octave
code, including stricter accepted types for several statistics functions.
Read both the current manual and NEWS before migrating to 11.3.0. The online
latest manual reviewed on this date identifies its generated content as
11.1.0 while the project download/news page identifies 11.3.0 as current;
consult NEWS-11 for the maintenance-release delta.
Reviewed Octave argv usually includes:
["octave", "--no-init-all", "--no-history", "--quiet", "--no-gui", "main.m"]
The bundled planner returns argv but never executes it.
Current manual behavior:
--eval/-e evaluates code and exits unless --persist is set;--no-gui selects CLI;--no-window-system disables graphics/window-system use;--no-init-all/--norc skips system and user initialization;--path adds a function path;--quiet suppresses greeting; --no-history avoids history writes.Octave startup can execute site/version files, user configuration,
project-local .octaverc, and MATLAB-compatible startup.m. Skipping all
startup files can improve reproducibility but can also remove expected package
or path setup. Review the plan.
MATLAB uses -batch, has different startup processing, and has no Octave
--no-init-all option. Never pass the same flags to both.
Prefer:
% comments;... continuation;end block terminators;x = x + 1;&&/|| for scalar conditions;.m functions with matching filenames.Avoid these Octave-only extensions in portable code:
# comments;endif, endfor, endfunction;++, --, +=, and related compound assignment;do ... until;Both support implicit expansion/broadcasting in many modern cases, but special classes and edge cases differ. Octave 11 expanded broadcasting for special matrix types. Test orientation, sparse output, empty dimensions, and mixed classes in both.
The current Octave manual does not establish drop-in equivalents for:
arguments blocks and all validators/name-value semantics;table/timetable workflows and their R2026a JSON conversions;runtests;matlab.unittest, MATLAB Test, Code Quality Dashboard;.mlx, App Designer .mlapp, .fig object compatibility;classdef, events/listeners, serialization, and metaclass
behavior.Use feature detection and separate adapters only after testing. Do not silently replace a missing MATLAB toolbox function with a similarly named Octave package function.
Octave packages are distributed separately from core Octave. MATLAB toolboxes are separately licensed MathWorks products. APIs, algorithms, defaults, validation, object models, and release schedules differ.
Never run pkg install, load an untrusted package, or alter .octaverc
automatically. Package installation can fetch/build/execute code. Record exact
package name/version/source/checksum and obtain approval.
pkg load mutates the function path and can shadow core or project functions.
Test which/resolution only in a trusted approved runtime.
Octave's built-in self-test system scans %! blocks and uses test. It is not
matlab.unittest.
%!test
%! observed = hypot(3, 4);
%! assert(observed, 5, 1e-12);
Portable production functions and runtime-specific test harnesses should be separate when test syntax differs. The nonexecuting planner can prepare an Octave BIST argv, but an approved runtime is required to run it.
Octave 11 supports writing MATLAB v4, v6, and v7 binary formats. It does not implement saving MATLAB v7.3.
Octave can save its own HDF5 representation when built with HDF5. Its load -hdf5 has limited ability to read MATLAB v7.3, mainly for supported numeric
content; many types are unsupported. An Octave HDF5 file is not automatically
a MATLAB v7.3 file.
Octave's current manual states that classdef objects are saved as structures
in supporting formats and are not restored as classdef objects. This differs
substantially from MATLAB object serialization.
Never load untrusted MAT/HDF5 files in either runtime. Use the bundled bounded technical inventory first, then escalate object/opaque/function/external-link content.
For portable simple data, use MATLAB v7 only after testing classes, shapes, text, sparse/complex values, and metadata. Prefer schema-documented language-neutral formats where feasible.
Basic calls such as plot, labels, legends, images, surfaces, and print are
similar, but renderers, fonts, properties, layout, transparency, callbacks,
and export formats differ.
Do not assume Octave implements R2026a exportgraphics, SVG/HTML web canvas,
tiledlayout, UI objects, or property behavior. Build a small compatibility
test and compare exported dimensions, font embedding, vector/raster content,
colors, and clipping.
Octave 11 NEWS documents graphics compatibility changes such as colorbar and event-field behavior. Review NEWS for each update.
Even when both runtimes call similarly named LAPACK/BLAS-backed functions, results can differ because of:
Compare residuals, invariants, objective/feasibility, and domain observables. Do not demand identical eigenvector signs, cluster bases, or bitwise floating-point output without a justified contract.