Solved! ‘extconf.rb failed’ LoadError 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: Is SQLite3 Already Installed?

First, check if SQLite3 is already installed. Run this command:

sqlite3 --version

If it spits out a version number, you’re good on that front. If not, you’ll need to install it.

Step 2: Install SQLite3 and Development Tools

Depending on your OS, the steps to install SQLite3 and its dev tools are different.

For Ubuntu/Debian Users

Run these commands:

sudo apt update
sudo apt install sqlite3 libsqlite3-dev

For Fedora Users

Run this:

sudo dnf install sqlite sqlite-devel

For macOS Users

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"

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

On Fedora

sudo dnf groupinstall "Development Tools"

On macOS

Install Xcode’s command-line tools:

xcode-select --install

Step 4: Install the sqlite3 Gem

Now that your system is ready, install the gem:

gem install sqlite3

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

gem 'sqlite3', '~> 1.4'

Then run:

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.

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