Ruby sqlite3 Gem Build Fails - Missing libsqlite3 in CI

The sqlite3 gem compiles a native extension against the SQLite library. Building from source needs libsqlite3 and its header; without them the extconf check fails. Recent versions also ship a precompiled gem that avoids this.

What this error means

bundle install fails installing sqlite3 with a missing sqlite3.h, a failed extconf, or a link error for -lsqlite3. The runtime sqlite binary alone does not provide the development headers.

mkmf output

checking for sqlite3.h... no
sqlite3.h is missing. Try 'brew install sqlite3',
'yum install sqlite-devel' or 'apt-get install libsqlite3-dev'
*** extconf.rb failed ***

Common causes

SQLite development headers not installed

The gem needs sqlite3.h and libsqlite3 to compile when building from source. The runtime package does not include the -dev files.

Forced source build instead of the precompiled gem

If x86_64-linux is not locked or force_ruby_platform is set, the gem compiles from source and needs the system library that the precompiled gem would have bundled.

How to fix it

Install the SQLite dev package

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y libsqlite3-dev
# Alpine
apk add --no-cache sqlite-dev
# RHEL/Fedora
dnf install -y sqlite-devel

Or use the precompiled platform gem

Recent sqlite3 releases ship a precompiled gem that bundles SQLite - lock the platform to use it.