An Octave kernel for Jupyter
It is recommended to also install
gnuplot for Octave to enable inline plotting.
To install using pip:
pip install octave_kernel
--user to install in the user-level environment instead of the system environment.
To install using conda:
conda config --add channels conda-forge conda install octave_kernel conda install texinfo # For the inline documentation (shift-tab) to appear.
We require the
octave-cli executable to run the kernel.
Add that executable's directory to the
PATH environment variable or use the
OCTAVE_EXECUTABLE to point to the executable itself.
Note that on Octave 5 on Windows, the executable is in
We automatically install a Jupyter kernelspec when installing the
python package. This location can be found using
jupyter kernelspec list.
If the default location is not desired, remove the directory for the
octave kernel, and install using
python -m octave_kernel install. See
python -m octave_kernel install --help for available options.
To use the kernel, run one of:
jupyter notebook # or ``jupyter lab``, if available # In the notebook interface, select Octave from the 'New' menu jupyter qtconsole --kernel octave jupyter console --kernel octave
This kernel is based on MetaKernel,
which means it features a standard set of magics (such as
%%html). For a full list of magics,
%lsmagic in a cell.
A sample notebook is available online.
The kernel can be configured by adding an
octave_kernel_config.py file to the
jupyter config path. The
OctaveKernel class offers
cli_options as configurable traits. The available plot settings are:
'format', 'backend', 'width', 'height', 'resolution', and 'plot_dir'.
cat ~/.jupyter/octave_kernel_config.py # use Qt as the default backend for plots c.OctaveKernel.plot_settings = dict(backend='qt')
The path to the Octave kernel JSON file can also be specified by creating an
OCTAVE_KERNEL_JSON environment variable.
The command line options to Octave can also be specified with an
OCTAVE_CLI_OPTIONS environment variable. The cli options be appended to the
default opions of
--interactive --quiet --no-init-file. Note that the
init file is explicitly called after the kernel has set
more off to prevent
a lockup when the pager is invoked in
The inline toolkit is the
graphics_toolkit used to generate plots for the inline
backend. It defaults to
gnuplot. The different backend can be used for inline
plotting either by using this configuration or by using the plot magic and putting the backend name after
plot -b inline:fltk.
Kernel Times Out While Starting
If the kernel does not start, run the following command from a terminal:
python -m octave_kernel.check
This can help diagnose problems with setting up integration with Octave. If in doubt, create an issue with the output of that command.
Kernel is Not Listed
If the kernel is not listed as an available kernel, first try the following command:
python -m octave_kernel install --user
If the kernel is still not listed, verify that the following point to the same version of python:
which python # use "where" if using cmd.exe which jupyter
An error that starts with
gnuplot> set terminal aqua enhanced title can be fixed by
~/.octaverc on MacOS or by installing
gunplot-x11 and using
You can check if you are using a snap version on Linux by checking the path to your Octave installation.
If the returned path has
snap in it, then Octave is running in a container and you will need to configure the kernel appropriately.
- Set the environment variable
echo export OCTAVE_EXECUTABLE=\"octave\" >> ~/.bashrc
- Make a directory for the temporary plot directories that the kernel uses. This cannot be a hidden directory.
plot_dirto point to your plot directory in
c.OctaveKernel.plot_settings = dict(plot_dir='<home>/octavePlots')
<home> is the absolute path to your home directory. Do not use
~ as this resolves to a different location for Octave-Snap.
Specify a different format using the
%plot -f <backend> magic or using a configuration setting.
On some systems, the default
'png' produces a black plot. On other systems
'svg' produces a