Ruby Gem Build "fatal error: ruby.h: No such file" in CI

The compiler ran but could not find ruby.h, the core Ruby development header every C extension includes. The header ships in the ruby-dev/ruby-devel package, separate from the interpreter - and it must match the active Ruby.

What this error means

A native gem build fails with "fatal error: ruby.h: No such file or directory" and "Failed to build gem native extension". The compiler exists (this is not a missing-compiler error); it simply cannot find the Ruby headers.

build output

compiling extension.c
extension.c:1:10: fatal error: ruby.h: No such file or directory
    1 | #include <ruby.h>
      |          ^~~~~~~~
compilation terminated.

Common causes

Ruby development headers not installed

The base Ruby package omits the C headers. Compiling any extension needs the separate dev package (ruby-dev on Debian/Ubuntu, ruby-devel on RHEL/Fedora).

Headers for the wrong Ruby version

A distro ruby-dev may not match a hand-built or rbenv Ruby. The build uses the active interpreter’s include path, so the headers must belong to that Ruby.

How to fix it

Install the matching Ruby dev headers

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y ruby-dev
# RHEL/Fedora
dnf install -y ruby-devel

For rbenv/asdf Ruby, use the build’s own headers

A Ruby built via ruby-build includes its headers. If ruby.h is still not found, the build is shelling out to a different Ruby.