opam "command not found" after setup-ocaml in CI

The shell could not find an opam executable on PATH. In CI this almost always means the step ran before the setup-ocaml action installed opam, or in a job that never invoked it.

What this error means

A step calling opam ... fails with "opam: command not found" and the job exits with code 127, while later steps that depend on OCaml never run.

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

Common causes

A step ran before setup-ocaml

opam is installed by the setup-ocaml action; any step ordered before it has no opam on PATH.

setup-ocaml was never added to the job

The workflow calls opam directly on a runner image that does not ship it, so the binary is simply absent.

How to fix it

Provision opam with setup-ocaml first

Run the setup-ocaml action before any opam or dune step so opam and the switch are on PATH.

- uses: ocaml/setup-ocaml@v3
  with:
    ocaml-compiler: '5.1'
- run: opam install . --deps-only --yes

Check ordering and shell

1. Confirm the setup-ocaml step runs before any opam call.
2. Keep opam steps in the same job so PATH set by the action applies.
3. Avoid switching to a shell that resets PATH between steps.

How to prevent it

• Always place setup-ocaml as the first OCaml-related step.
• Group opam and dune steps in one job so PATH is consistent.
• Do not assume runner images ship opam by default.

Related guides