Fixed! ‘extconf.rb failed’ Error in Ruby gem sqlite3

Running into trouble with the sqlite3-ruby gem and seeing errors about extconf.rb or mkmf? Don’t worry—you’re not the only one. This is a pretty common snag, especially for folks working on Ruby projects that use SQLite as their database. The good news? It’s not as scary as it looks. Here’s how to fix it.

Why You’re Getting the LoadError

This error shows up when the sqlite3-ruby gem can’t find the libraries or tools it needs to build its native extensions. You’ll see something like this:

checking for sqlite3.h... no
sqlite3.h is missing. Install SQLite3 from your package manager.
*** extconf.rb failed ***

Basically, your system is missing the SQLite3 development files, which include the headers and libraries the gem needs to compile.

Here’s how to get everything working based on your operating system:

Step 1: Check If SQLite3 Is Installed

Before installing anything, verify if SQLite3 is already installed on your system:

sqlite3 --version

If you see an error like command not found: sqlite3, you need to install SQLite3.

If this command outputs a version number, SQLite3 is already installed, and the problem likely lies elsewhere.

Step 2: Install SQLite3 and Development Tools

The installation steps depend on your operating system.

For Ubuntu/Debian Users

Run these commands:

sudo apt update
sudo apt install sqlite3 libsqlite3-dev

sqlite3 installs the SQLite database engine.libsqlite3-dev includes header files needed to compile the sqlite3-ruby gem. Without this package, you’ll see the sqlite3.h is missing error.

Alternative: If you are using snap, try:

sudo snap install sqlite3

For Fedora Users

Run the following command:

sudo dnf install sqlite sqlite-devel

• sqlite installs SQLite.
• sqlite-devel provides the development files required for building Ruby’s SQLite extension

For macOS Users (Homebrew)

If you’re on macOS and using Homebrew, do this:

brew install sqlite3

If you still have issues, check that SQLite3’s location is in your PATH. Add it to your shell config file like this:

export PATH="/usr/local/bin:$PATH"

Then verify it:

which sqlite3
sqlite3 --version

Alternative for macOS Users (MacPorts):

sudo port install sqlite3

For those working extensively with Linux commands, it’s useful to list all installed RPM packages to check if SQLite3 is already available.

Step 3: Make Sure Ruby and Build Tools Are Updated

Outdated Ruby or missing build tools can also cause problems. Here’s how to get everything up to date:

On Ubuntu/Debian

sudo apt install build-essential

Installs the GCC compiler, Make, and other essential tools required to compile native extensions in Ruby.

On Fedora

sudo dnf groupinstall "Development Tools"

This installs a collection of compilers, linkers, and debugging tools required to build Ruby gems with native extensions.

On macOS

Install Xcode’s command-line tools:

xcode-select --install

Installs Apple’s Command Line Tools, which include the clang compiler and other tools required for Ruby native extensions.

If you’re troubleshooting package dependencies, you might also want to learn how to handle RPM installation dependencies.

Step 4: Install the sqlite3 Gem

Once SQLite3 and the necessary development tools are installed, install the Ruby gem:

gem install sqlite3

The sqlite3 gem is a Ruby interface for SQLite databases. This command downloads and compiles the latest compatible version for your system.

If you’re using Rails, add this to your Gemfile:

gem 'sqlite3', '~> 2.5'

Then install it with:

bundle install

Common Issues and Fixes

Still stuck? Here are a few extra things to try:

• Reinstall the Gem: Sometimes starting fresh helps: gem uninstall sqlite3 gem install sqlite3
• Check Your Compiler: If you’re using an older compiler, it might not work with your Ruby version. Update your compiler if needed.
• Set Build Flags: If the gem can’t find the SQLite3 headers, point it in the right direction: gem install sqlite3 -- --with-sqlite3-include=/path/to/sqlite3/include --with-sqlite3-lib=/path/to/sqlite3/lib
• Use a Compatible Ruby Version: Check the gem’s documentation to make sure your Ruby version is supported.

If you’re dealing with system storage issues, you may also need to free up disk space on Linux before installing dependencies.

Wrapping Things Up

Errors with extconf.rb and mkmf can feel like a hassle, but they’re totally solvable. Just make sure SQLite3 and its dev libraries are installed, your Ruby setup is updated, and you’ve got the right build tools. Once everything’s in place, installing the sqlite3-ruby gem should work like a charm.

FAQ