Raspberry Pi OS
The official Debian-based operating system for Raspberry Pi computers.
os
also known as Raspbian, Raspberry Pi OS Bookworm, Raspberry Pi OS Lite
Knowledge about Raspberry Pi OS
- Building your own Raspberry Pi OS image for a device fleet: rpi-image-gen and pi-gen-microrecommendation · unverified · Instead of hand-configuring each SD card, build a reproducible image from declarative config. rpi-image-gen builds customised images from Raspberry Pi OS packages (with SBOM/CVE reports and secure-boot integration); pi-gen-micro builds tiny embedded systems.
- Debug GPIO from the shell with pinctrl: see pin modes, set levels, watch signalscode · unverified · pinctrl from raspberrypi/utils replaces raspi-gpio. It shows every GPIO's function and level, sets pins, lists alternate functions, and can poll pins as a basic logic analyser for slow signals.
- Diagnose Raspberry Pi throttling and undervoltage with vcgencmd get_throttledprocedure · unverified · Decode vcgencmd get_throttled to tell undervoltage from overheating, read the SoC temperature, and know when the Pi throttles (80–85 °C) and how the Pi 5 fan responds.
- Don't run rpi-update on production devices: it installs bleeding-edge firmware and kernelswarning · unverified · rpi-update installs pre-release kernel and firmware builds that may contain regressions. Raspberry Pi's own README says to use it only for testing or to get a specific pending fix; normal updates come through apt.
- Enable I2C, SPI and UART on Raspberry Pi, and avoid the serial console and Bluetooth conflictsprocedure · unverified · Turn on I2C/SPI/serial with raspi-config, disable the serial login console when a device needs the UART, know that Bluetooth occupies a UART on wireless models, and that Pi 5's primary UART is the debug header.
- Headless Raspberry Pi setup: there is no default 'pi' user anymoreprocedure · unverified · Since the April 2022 Raspberry Pi OS release there is no default pi user. For headless IoT devices, preconfigure user, Wi-Fi and SSH in Raspberry Pi Imager's customisation, or use userconf.txt and the ssh file on the boot partition.
- Identify a Raspberry Pi in code: serial number for the device ID, device tree for the modelprocedure · unverified · For fleet IDs, read the board's unique serial number instead of relying on hostname, IP or MAC. For model detection, use /proc/device-tree/compatible or the board-type field of the revision code, never the 'Hardware: BCM2835' line or a list of exact revision codes.
- Let a frozen Raspberry Pi reboot itself: the hardware watchdog via systemd (max 15 s)procedure · unverified · Remote Pis occasionally hang. systemd can drive the built-in hardware watchdog with RuntimeWatchdogSec in /etc/systemd/system.conf, with no extra daemon. The bcm2835 watchdog can't time out after more than 15 seconds, so keep the value at or below that.
- Prevent SD card corruption on Raspberry Pi IoT devicesguide · unverified · Sudden power loss and bad supplies corrupt SD cards. Combine a good power supply, fewer writes, a read-only root with overlayfs (raspi-config), a UPS where possible, and SSD/NVMe boot on Pi 5.
- RPi.GPIO edge detection broke with kernel 6.6 (not only on Pi 5): switch to rpi-lgpio or gpiozerowarning · unverified · Since Raspberry Pi's 6.6 kernel, global GPIO numbers start at 512 instead of 0, and RPi.GPIO calls such as add_event_detect fail even on a Pi 4. Raspberry Pi engineers point to rpi-lgpio (same API, apt package python3-rpi-lgpio) or gpiozero. On Pi 5 the header GPIOs moved from gpiochip4 to gpiochip0.
- Reach a headless Raspberry Pi over one USB cable: the rpi-usb-gadget Ethernet gadgetprocedure · unverified · rpi-usb-gadget makes the Pi appear as a USB network adapter to the host (CDC-ECM on Linux/macOS, RNDIS on Windows). It switches automatically between using the host's connection sharing and serving DHCP/NAT itself at 10.12.194.1/28.
- Run a Python IoT script as a systemd service that restarts on failurecode · unverified · A minimal systemd unit for a Raspberry Pi gateway script: starts at boot after the network, runs as its own user from a venv, restarts on failure, logs to the journal.
- Shut down a headless Raspberry Pi safely: a button instead of pulling the plugprocedure · unverified · Pulling the power risks SD card and file system damage. Give headless devices a shutdown button: the onboard power button (or J2 pads) on Pi 5, the gpio-shutdown overlay on earlier models. The default GPIO3 button also powers the board back on, but GPIO3 is the I2C clock pin.
- Wired-only Raspberry Pi: disable onboard Wi-Fi and Bluetooth in config.txtprocedure · unverified · For devices on Ethernet, turn the unused radios off in firmware with dtoverlay=disable-wifi and dtoverlay=disable-bt in /boot/firmware/config.txt. On models before the Pi 5, disabling Bluetooth also gives the full UART on GPIO 14/15 back.
- pip install fails with 'externally-managed-environment' on Raspberry Pi OS Bookwormwarning · unverified · Since Bookworm, pip can only install into a virtual environment (PEP 668). Use apt for system packages or a venv for your project; --system-site-packages keeps apt-installed libraries like gpiozero available.