Masz Raspberry Pi i zastanawiasz się, jaki Linux wybrać, żeby wszystko działało stabilnie i bez męczącej walki z błędami? Z tego poradnika dowiesz się, które dystrybucje sprawdzają się najlepiej i czym się kierować przy wyborze. Zobaczysz też, jak uniknąć pułapek związanych z bibliotekami, kompilacją i obsługą ARM.
Jakie systemy Linux są najczęściej używane na Raspberry Pi?
Większość użytkowników zaczyna od Raspberry Pi OS, ale w praktyce na małej płytce działa bardzo wiele systemów. Na wybór wpływa architektura (armhf, arm64), dostępność pakietów i to, czy planujesz desktop, czy serwer. Przy projektach z Node.js, npm, modułami natywnymi jak node-canvas albo node-gyp ważne są też biblioteki developerskie i stabilność ABI.
W wielu projektach – takich jak boty Discord działające na ZeroBot, aplikacje webowe, dashboardy czy automatyka domowa – Raspberry Pi pracuje jako mały serwer. Wtedy na pierwszy plan wysuwają się systemy oparte na Debianie lub Ubuntu, bo mają dojrzałe repozytoria, znany system pakietów i dobre wsparcie dla kompilacji. To właśnie na takich systemach pojawiają się komunikaty w stylu Failed to execute node-gyp build czy błędy brakujących nagłówków C, więc dobry wybór dystrybucji często oszczędza dużo czasu.
Raspberry Pi OS
Raspberry Pi OS (dawniej Raspbian) to domyślny system polecany przez fundację. Bazuje na Debianie i jest dostosowany do sprzętu Raspberry – zawiera sterowniki, narzędzia konfiguracyjne i obrazy zoptymalizowane pod ARM. Występuje w wersjach Lite (bez środowiska graficznego) oraz z desktopem.
Wariant Raspberry Pi OS Lite świetnie sprawdza się jako baza pod serwery Node.js, bazy danych czy kontenery. System jest lekki, ma małe zużycie RAM, a przy tym oferuje łatwy dostęp do bibliotek jak build-essential, python3, libc6-dev czy libstdc++, które są potrzebne, aby uniknąć błędów w stylu fatal error: stddef.h: No such file or directory podczas kompilacji.
Ubuntu Server dla Raspberry Pi
Drugim bardzo popularnym wyborem jest Ubuntu Server dla ARM. Wiele osób używa wariantów Ubuntu 20.04 LTS lub 22.04 LTS, bo dają długie wsparcie i nowsze wersje pakietów niż Debian. Dla użytkowników Node.js ważne jest też wygodne korzystanie z nvm i różnych wersji Node, co na Ubuntu zwykle działa bez problemów.
Ubuntu Server na Raspberry Pi ma jednak pewien haczyk. Domyślna instalacja bywa dość „goła” i nie zawiera od razu wszystkich narzędzi developerskich. Jeśli chcesz budować moduły natywne jak canvas, konieczna jest szybka instalacja paczek typu build-essential oraz libc6-dev. Brak nagłówków może prowadzić dokładnie do takich komunikatów jak w logach z kompilacji canvas – system niby działa, ale kompilator C++ nie znajduje podstawowych plików, np. stddef.h.
Na co zwrócić uwagę wybierając Linux do Raspberry Pi?
Sam wybór nazwy systemu to dopiero początek. Dwa Raspberry Pi z tym samym „Ubuntu 22.04” mogą zachowywać się inaczej, jeśli jedno ma doinstalowane pakiety developerskie, a drugie powstało z nie do końca poprawnie odtworzonego obrazu po awarii karty SD. To właśnie takie różnice często tłumaczą sytuację, w której na jednym urządzeniu npm i canvas działa, a na drugim kończy się błędem.
Przy planowaniu projektu warto od razu założyć, że będziesz kompilować coś z użyciem node-gyp. Nawet jeśli dziś instalujesz tylko proste paczki npm, jutro możesz dodać bibliotekę wymagającą kompilacji względem systemowych nagłówków. Wtedy brak pakietów typu linux-headers czy libc6-dev natychmiast wyjdzie na jaw.
Architektura – armhf czy arm64?
Raspberry Pi potrafi pracować zarówno w wariancie 32-bitowym (armhf), jak i 64-bitowym (arm64). Różnica nie kończy się na liczbie bitów. System 64-bitowy używa innych binariów, a gotowe paczki i prebuildy – jak te dla node-canvas umieszczone na GitHub – często są przygotowane tylko dla wybranych kombinacji Node/ABI/system.
W logach kompilacji pojawia się informacja linux | arm64 oraz próba pobrania paczki z adresem zawierającym linux-glibc-arm64. Jeśli dla danej wersji canvas i Node nie ma prekompilowanego archiwum, node-pre-gyp przechodzi w tryb „fallback-to-build” i wymaga pełnego środowiska developerskiego. W przypadku 32-bitowego Raspberry Pi OS częściej dostępne są gotowe binaria, ale przy nowoczesnych projektach coraz częściej warto postawić na arm64 i dopilnować instalacji wszystkich nagłówków.
Środowisko developerskie i kompilacja
Brak pliku stddef.h to typowy sygnał, że nie są zainstalowane pakiety z nagłówkami standardowych bibliotek C. Na świeżym systemie serwerowym, szczególnie po ręcznej rekonfiguracji czy odtwarzaniu z obrazu, taki stan nie jest niczym dziwnym. Dla dystrybucji bazujących na Debianie standardem jest polecenie, które rozwiązuje większość podobnych problemów jednym strzałem:
apt install build-essential libc6-dev na Debianie, Raspberry Pi OS lub Ubuntu zwykle przywraca kompletny zestaw nagłówków C/C++ potrzebnych do kompilacji modułów Node.
Warto od razu zadbać również o python3 oraz powiązane z nim pakiety, bo node-gyp używa Pythona do generowania plików konfiguracji. W przeciwnym razie logi będą pełne komunikatów o błędach podczas wywoływania gyp_main.py, mimo że sam Node i npm są poprawnie zainstalowane przez nvm.
Jak dobrać system Linux do typowych zastosowań Raspberry Pi?
Inne wymagania ma osoba uruchamiająca prosty serwer WWW z jednym botem Discord, a inne ktoś, kto chce stworzyć pracownię testową z wieloma kontenerami, bazami danych i serwisami. Dobry dobór systemu pod konkretny scenariusz pozwala potem uniknąć desperackiego odtwarzania uszkodzonych obrazów i mozolnego „łatania” brakujących bibliotek.
W wielu przypadkach przejrzysty podział zastosowań pomaga szybciej wybrać dystrybucję. Jeśli na jednym Raspberry chcesz mieć desktop, a drugie ma stać w szafce i hostować usługi, można bez problemu użyć dwóch różnych systemów – na przykład Raspberry Pi OS Desktop na pierwszym i Ubuntu Server na drugim.
Serwery Node.js, boty, aplikacje webowe
Dla aplikacji napisanych w Node.js, korzystających z npm i wymagających czasem kompilacji – jak boty Discord oparte na ZeroBot, aplikacje panelowe czy dashboardy – bardzo dobrym wyborem jest Ubuntu Server arm64 lub Raspberry Pi OS Lite. Oba systemy da się łatwo skonfigurować z użyciem nvm, Node 18 czy 20 oraz zainstalować wszystkie biblioteki developerskie.
To właśnie w takim środowisku pojawiają się błędy w stylu npm ERR! gyp ERR! build error. Gdy system jest świeży, zwykle wystarczy doinstalować pakiety developerskie, a kompilacja canvas i podobnych modułów przechodzi bez problemu. Dużo trudniej pracuje się na systemie odtworzonym z nie do końca spójnego obrazu po awarii karty, gdzie część pakietów mogła zostać pominięta lub ma niespójne wersje.
Proste projekty hobby i nauka programowania
Jeśli Raspberry Pi ma służyć głównie do nauki Pythona, prostych skryptów GPIO czy pracy z Scratch, wygodniej jest postawić na Raspberry Pi OS Desktop. To gotowy system z graficznym środowiskiem, przeglądarką, narzędziami edukacyjnymi oraz repozytoriami zgodnymi z bibliotekami sprzętowymi Pi.
W takim scenariuszu problemy z kompilacją natywnych modułów Node pojawiają się rzadziej, bo niewiele osób instaluje cięższe biblioteki. Jeśli jednak sięgasz po npm i moduły pokroju canvas, nic nie stoi na przeszkodzie, aby także na desktopowym wydaniu doinstalować build-essential, libc6-dev i działać podobnie jak na serwerze.
Środowiska produkcyjne i wiele usług
Gdy Raspberry Pi ma obsługiwać kilka usług jednocześnie, np. reverse proxy, bazę danych, bota Discord i panel WWW, pojawia się pokusa użycia Docker lub innej technologii kontenerowej. W takich scenariuszach dobrze sprawdza się Ubuntu Server, bo ma szerokie wsparcie dla narzędzi DevOps.
Trzeba tylko pamiętać, że kontenery nie rozwiązują problemu brakujących nagłówków w systemie bazowym. Jeśli obraz kontenera buduje moduły natywne, to i tak musi mieć w środku gcc, g++, libc6-dev czy inne pliki nagłówkowe. W praktyce wygodnie jest wtedy wybrać taką dystrybucję, dla której istnieją gotowe, aktualne obrazy bazowe z pełnym build-essential.
Jak porównać dystrybucje Linux dla Raspberry Pi?
Jeśli wciąż wahasz się między Raspberry Pi OS i Ubuntu albo rozważasz też inne systemy jak DietPi, warto porównać je pod kątem kilku konkretnych cech. Liczy się nie tylko wygoda instalacji, ale też to, czy łatwo znajdziesz gotowe paczki, czy system dobrze obsługuje arm64 i jak prosto uzupełnisz brakujące biblioteki developerskie.
Przy projektach wymagających kompilacji istotne staje się też to, czy system ma aktywne wsparcie bezpieczeństwa, regularne aktualizacje kernela (np. Linux 5.15.0-1024-raspi) oraz jak często pojawiają się nowe obrazy do pobrania. Stare lub uszkodzone obrazy kart SD bywają źródłem trudnych do odtworzenia błędów, a świeża instalacja często bywa szybsza niż długie dochodzenie, czemu brakuje konkretnego stddef.h.
| Dystrybucja | Typowe zastosowanie | Plus przy kompilacji Node |
| Raspberry Pi OS Lite | Serwery, projekty IoT, małe usługi | Łatwy dostęp do build-essential na armhf i arm64 |
| Ubuntu Server arm64 | Aplikacje Node, Docker, wiele usług | Nowsze wersje bibliotek, dobre wsparcie dla node-gyp |
| Raspberry Pi OS Desktop | Nauka, praca z GUI, projekty edukacyjne | Pełne repozytoria Debiana, możliwość doinstalowania narzędzi developerskich |
Jak uniknąć różnic między dwoma Raspberry Pi?
Sytuacja, w której jeden Raspberry Pi buduje pakiet canvas bez problemu, a drugi wyrzuca błędy, często wynika z różnic w konfiguracji. Na jednym system jest świeży i ma pełne zależności, a na drugim wykonano przywracanie z obrazu po uszkodzeniu karty SD i naprawę tylko widocznych błędów pakietów.
Aby ujednolicić środowiska, można zastosować prosty zestaw kroków. Najpierw aktualizacja systemu, potem instalacja narzędzi do kompilacji, a na końcu porównanie wersji Node, npm i używanego node-gyp. Taka procedura często „magicznie” usuwa różnice, których nie widać gołym okiem.
Dla czytelności warto zebrać podstawowe kroki konfiguracji Debian/Ubuntu na Raspberry Pi, które pomagają uniknąć błędów przy budowaniu modułów npm jak canvas:
- aktualizacja list pakietów przez apt update i apt upgrade,
- instalacja pakietu build-essential zawierającego gcc, g++ i make,
- doinstalowanie libc6-dev oraz innych nagłówków C/C++,
- sprawdzenie, czy python3 jest dostępny w /usr/bin/python3.
Drugim krokiem jest upewnienie się, że środowisko Node jest takie, jakiego oczekuje projekt. Przy nvm można łatwo przełączać wersje i warto z tego korzystać, aby uniknąć sytuacji, w której jedna maszyna używa Node 18.14.0, a druga innego wydania z odmiennym ABI:
- sprawdź wersję Node komendą node -v,
- porównaj wersję npm i node-gyp z logami błędów,
- w razie potrzeby zainstaluj identyczną wersję Node na obu urządzeniach,
- zbuduj od nowa folder node_modules po zmianie wersji Node.
Gdy dwa Raspberry Pi mają ten sam obraz systemu, taki sam zestaw pakietów developerskich i taką samą wersję Node, szansa na tajemnicze błędy typu „no such file or directory” podczas kompilacji modułów npm spada praktycznie do zera.
Jak świadomie wybrać Linux do swojego Raspberry Pi?
Wybór dystrybucji Linux dla Raspberry Pi dobrze jest powiązać bezpośrednio z tym, co chcesz na nim uruchomić. Dla prostych projektów hobbystycznych wystarczy Raspberry Pi OS Desktop. Dla serwerów i aplikacji Node.js lepiej sprawdza się Raspberry Pi OS Lite lub Ubuntu Server na arm64, ale z pełnym zestawem narzędzi kompilacyjnych.
Gdy Twoje projekty mocno korzystają z npm, node-pre-gyp i modułów natywnych, system powinien oferować wygodny dostęp do build-essential, libc6-dev, nagłówków kernela i Pythona. To one stanowią ciche zaplecze każdej poprawnej kompilacji i decydują, czy polecenie npm i canvas zakończy się błędem, czy spokojnym „done” w terminalu.
