Tutorial: Fehler "Failed to build gem native extension" beheben

Hier ist ein ausführliches Tutorial, wie du den häufigen Fehler bei der Installation von Ruby on Rails beheben kannst.

Dieser Fehler tritt auf, wenn Ruby versucht, ein Gem zu installieren, das C-Erweiterungen enthält (z. B. nokogiri, sqlite3 oder pg), aber die dafür notwendigen System-Header oder Compiler-Tools auf deinem Betriebssystem fehlen.

1. Die Ursache verstehen

Ruby-Gems sind oft in Ruby geschrieben, aber performante Teile nutzen C-Code. Damit dieser Code auf deinem Computer läuft, muss er während der Installation „kompiliert“ werden. Wenn die Fehlermeldung erscheint, bedeutet das meist: Dir fehlen die Build-Tools oder die Entwicklungs-Bibliotheken (Headers) für dein System.

2. Lösung für Linux (Ubuntu / Debian / Mint)

Auf Linux-Systemen fehlen meist die Basis-Entwicklungspakete und die Ruby-spezifischen Header.

Schritt 1: System-Pakete aktualisieren Öffne das Terminal und gib ein:

sudo apt update

Schritt 2: Build-Essentials und Ruby-Header installieren Installiere die wichtigsten Tools und die Header-Dateien für Ruby:

sudo apt install build-essential libssl-dev libreadline-dev zlib1g-dev ruby-dev

Schritt 3: Spezifische Bibliotheken (falls nötig) Falls der Fehler weiterhin bei einem bestimmten Gem (z. B. sqlite3 oder pg) auftritt, installiere die jeweiligen Header:

• Für SQLite: sudo apt install libsqlite3-dev
• Für PostgreSQL: sudo apt install libpq-dev
• Für Nokogiri: sudo apt install libxml2-dev libxslt1-dev

3. Lösung für macOS

Auf dem Mac liegt das Problem meist an fehlenden oder nicht verknüpften Kommandozeilen-Tools von Xcode.

Schritt 1: Xcode Command Line Tools installieren Gib folgenden Befehl im Terminal ein:

xcode-select --install

Ein Fenster öffnet sich – klicke auf "Installieren".

Schritt 2: Homebrew nutzen (optional, aber empfohlen) Falls du Homebrew nutzt, stelle sicher, dass die Bibliotheken aktuell sind:

brew update
brew install openssl readline libyaml

4. Lösung für Windows

Unter Windows wird für das Kompilieren von Gems das sogenannte MSYS2 DevKit benötigt.

Schritt 1: DevKit installieren Wenn du Ruby über den RubyInstaller installiert hast, öffne die Eingabeaufforderung (CMD) und gib ein:

ridk install

Wähle im Menü die Option 3 (MSYS2 and MINGW development toolchain).

Schritt 2: Pfade aktualisieren Starte die Konsole neu, damit die neuen Pfade geladen werden.

5. Der finale Test

Nachdem du die oben genannten Tools installiert hast, kannst du versuchen, Rails (oder das betroffene Gem) erneut zu installieren:

gem install rails

Oder falls du Bundler nutzt:

bundle install

Zusammenfassung der häufigsten fehlenden Header:

Wenn die Fehlermeldung einen speziellen Namen nennt, hilft meist die Installation des entsprechenden -dev Pakets:

Tipp: Achte in der langen Fehlermeldung auf die Zeile Can't find header... oder checking for ... failure. Dort steht oft genau, welche Datei (z.B. zlib.h oder Python.h) vermisst wird.