gem "mkmf.rb can't find header files for ruby" in CI

To build a native extension, mkmf needs the Ruby C headers (ruby.h and friends). "mkmf.rb can't find header files for ruby" means the ruby-dev package for the running interpreter is missing.

What this error means

A native gem install fails with "mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h", stopping before the extension compiles.

gem

mkmf.rb can't find header files for ruby at
/usr/lib/ruby/include/ruby.h

You might have to install separate package for the ruby development
environment, ruby-dev or ruby-devel for example.

Common causes

The Ruby development headers are not installed

The image ships the Ruby runtime but not ruby-dev, so ruby.h is absent and mkmf cannot proceed.

A system Ruby without matching dev headers

The distro Ruby is used without installing the corresponding -dev package for that exact version.

How to fix it

Install the Ruby development package

Add ruby-dev (Debian/Ubuntu) matching the interpreter so ruby.h is present.

Terminal

sudo apt-get update
sudo apt-get install -y ruby-dev

Use setup-ruby, which ships headers

setup-ruby installs a self-contained interpreter that already includes the development headers.

.github/workflows/ci.yml

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.3'

How to prevent it

Install ruby-dev when building native gems against a system Ruby.
Prefer setup-ruby, which bundles the development headers.
Keep the -dev package version matched to the interpreter.