Raspberry Pi OS (formerly Raspbian): Practical Reference

Check what you're running with:

cat /etc/os-release
uname -m              # aarch64 = 64-bit, armv7l/armv6l = 32-bit
cat /proc/device-tree/model

Installing with Raspberry Pi Imager

Raspberry Pi Imager (for Linux, Windows and macOS) downloads the right image for your board and writes it to a microSD card, USB drive or NVMe adapter. On Linux, install it with sudo apt install rpi-imager, from Flathub, or from raspberrypi.com.

1. Choose your device, then the OS (Raspberry Pi OS 64-bit for most boards), then the storage.
2. When asked, edit the OS customisation settings: hostname, username and password, Wi-Fi network and country, locale, and SSH. This is the only way to get a working login on a headless Pi without a screen and keyboard.
3. For SSH, choose "Allow public-key authentication only" and paste your public key. If you don't have one yet, see setting up SSH keys.
4. Write, insert the card, power on. The first boot takes a minute or two longer while the filesystem expands.

Find the Pi on your network and connect:

ping raspberrypi.local          # or whatever hostname you set
ssh [email protected]

If .local names don't resolve, look up the IP in your router's DHCP list. If SSH rejects your key, see Permission denied (publickey).

Everyday tasks

Updating

sudo apt update
sudo apt full-upgrade
sudo reboot

Use full-upgrade, not just upgrade: Raspberry Pi kernel and firmware updates sometimes add or replace packages. For the full set of apt commands, see the apt guide. Moving to a new Debian base (for example bookworm to trixie) is not supported in place by Raspberry Pi; the recommended path is a fresh image and restoring your data.

raspi-config

sudo raspi-config

Text menus for hostname, password, boot to desktop or console, SSH/VNC/I2C/SPI/serial interfaces, Wi-Fi country, locale and expanding the filesystem. Most options are also available non-interactively, for example sudo raspi-config nonint do_ssh 0 to enable SSH.

Wi-Fi and static IP

nmcli device wifi list
sudo nmcli device wifi connect "MyNetwork" --ask
sudo nmtui                     # menu for static IPs and connection profiles

Older guides tell you to edit wpa_supplicant.conf or dhcpcd.conf; those don't apply to current Raspberry Pi OS, which uses NetworkManager. See Linux networking basics for nmcli static IP examples.

config.txt and firmware

Boot-time hardware settings live in /boot/firmware/config.txt (it was /boot/config.txt before bookworm). Common lines:

# enable the I2C bus
dtparam=i2c_arm=on
# disable onboard Bluetooth
dtoverlay=disable-bt

On Pi 4 and Pi 5, the bootloader lives in an EEPROM. Keep it current, which also adds USB and NVMe boot improvements:

sudo rpi-eeprom-update
sudo rpi-eeprom-update -a
sudo reboot

Python packages

Raspberry Pi OS inherits Debian's PEP 668 protection, so pip install outside a virtual environment fails with externally-managed-environment. Use apt packages (python3-<name>) or a venv:

python3 -m venv --system-site-packages ~/venv
source ~/venv/bin/activate
pip install <package>

--system-site-packages keeps access to preinstalled hardware libraries such as gpiozero and picamera2.

Common problems and fixes

Decode vcgencmd get_throttled values: bit 0 (0x1) means undervoltage right now, bit 16 (0x10000) means it has happened since boot. Any non-zero value is worth fixing before you chase software problems.

Alternatives on the Raspberry Pi

Raspberry Pi OS is the best-supported option, especially for camera modules, GPIO and displays. Ubuntu Desktop and Server publish official Pi images, Kali provides ARM images for security work (see the Kali reference), and for servers you can also run plain Debian on Pi 4 and later.

Frequently asked questions