Octave "octave: command not found" in CI

The shell could not find an octave executable. Hosted runners do not ship GNU Octave, so a bare octave call fails until you install it.

What this error means

A step running octave --eval ... fails with "octave: command not found" and exit code 127.

/home/runner/work/_temp/script.sh: line 1: octave: command not found
Error: Process completed with exit code 127.

Common causes

Octave is not installed on the runner

Hosted runners have no Octave by default, so the executable does not exist on PATH.

Only octave-cli exists

Some images install octave-cli but not the octave wrapper, so the bare name is missing.

How to fix it

Install Octave with apt

1. Install octave (and octave-cli) before any Octave step.
2. Run headless with octave-cli or octave --no-gui.
3. Verify with octave --version.

sudo apt-get update
sudo apt-get install -y octave octave-cli
octave-cli --version

Use a setup action

A dedicated Octave setup action provisions Octave across OSes without manual apt steps.

- uses: mccdaq/setup-octave@v1  # or an equivalent octave setup action
- run: octave-cli --eval "disp('ok')"

How to prevent it

• Install Octave explicitly before Octave steps on hosted runners.
• Prefer octave-cli or --no-gui for headless CI.
• Bake Octave into a custom image for self-hosted runners.

Related guides