This is a picture-first guide. Each numbered graphic is a step. You can install a desktop Linux, a headless server Linux, or a Linux you built yourself. The board stays the same. Only the image on the microSD card changes.
Key Abbreviations in This Post
- SBC (Single-Board Computer): A complete computer on one board. Raspberry Pi 5 and Pi 4 are SBCs.
- CLI (Command-Line Interface): Text terminal. No desktop. Used for servers and headless Pis.
- GUI (Graphical User Interface): Desktop with windows, mouse, and a monitor.
- Imager / rpi-imager: Official Raspberry Pi tool that writes an OS image to a card. Has GUI and CLI modes.
- Lite image: Raspberry Pi OS without a desktop. SSH and terminal only.
- Headless: Run the Pi with no monitor. You log in over the network.
- pi-gen: Official script that builds custom Raspberry Pi OS images.
- Yocto: Build system for reproducible embedded Linux (uses the meta-raspberrypi layer).
- Buildroot: Simpler builder for small appliance images.
- SSH (Secure Shell): Remote login over the network.
The One-Minute Version
- GUI desktop: Install Raspberry Pi Imager, pick your Pi model, pick Raspberry Pi OS Desktop (or Ubuntu Desktop), write the card, plug in HDMI, power on.
- CLI / headless: Same Imager, pick Raspberry Pi OS Lite (or Ubuntu Server). Turn on SSH and Wi-Fi in Imager settings. Power on. Then
ssh user@raspberrypi.local. - CLI from a Linux PC:
sudo rpi-imager --cli image.img.xz /dev/sdXafterlsblkconfirms the card. - Custom product image: Build with pi-gen, Yocto, or Buildroot. Flash the resulting
.imgthe same way. - Never guess the disk. Writing to the wrong
/dev/sdXwipes a laptop drive.
Match the image to the board. A Pi 5 image will not boot a Pi 3. Prefer 64-bit images unless you have a 32-bit-only reason.
- Raspberry Pi board and official 5 V USB-C supply (Pi 5 needs a capable 5 V / 5 A supply).
- microSD card, 16 GB or larger, Class A2 if you can.
- USB card reader on your PC.
- For GUI: HDMI cable, monitor, keyboard, mouse.
- For CLI: Ethernet or Wi-Fi, plus another computer for SSH.
| Flavor | Type | Use it when |
|---|---|---|
| Raspberry Pi OS Desktop | GUI | Best first image. Official drivers, camera, GPIO tools. |
| Raspberry Pi OS Lite | CLI | Headless servers, kiosks you SSH into, IoT. |
| Ubuntu Desktop / Server | GUI / CLI | You already know Ubuntu packages and cloud-init. |
| Debian | CLI (or add a desktop) | Closest to upstream Debian on Pi hardware. |
| DietPi | CLI | Small, fast, lots of one-click software recipes. |
| Alpine Linux | CLI | Tiny footprint, containers, appliances. |
| Fedora / Manjaro ARM | GUI | You want those desktop stacks on a Pi. |
- Download Imager from raspberrypi.com/software (Windows, macOS, or Linux). On Raspberry Pi OS:
sudo apt install rpi-imager. - Open Imager. Choose Device (Pi 5, Pi 4, Zero 2 W, and so on).
- Choose OS:
- Raspberry Pi OS (64-bit) for a desktop.
- Raspberry Pi OS Lite for CLI.
- Other general-purpose OS for Ubuntu, Alpine, and more.
- Choose Storage: your microSD (check the size so you do not pick the wrong disk).
- Open OS Customisation (gear): set hostname, username, password, Wi-Fi, locale, and enable SSH.
- Write. Eject. Insert the card in the Pi. Power on last.
# 1. See disks. Find the card by size.
lsblk
# 2. Unmount any auto-mounted partitions
sudo umount /dev/sdX1 /dev/sdX2
# 3a. Official CLI (verifies the write)
sudo rpi-imager --cli raspios.img.xz /dev/sdX
# 3b. Or classic pipeline
xzcat raspios.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
syncIf the card shows as /dev/mmcblk0, write to /dev/mmcblk0, not mmcblk0p1.
Complete country, timezone, password, and updates. Enable SSH in Raspberry Pi Configuration if you will leave the monitor later. Then sudo apt update && sudo apt full-upgrade.
ssh youruser@raspberrypi.local
# or ssh youruser@192.168.x.x (check your router)On current Raspberry Pi OS, Imager writes first-boot settings for you. That is safer than hand-editing the boot partition. If you must do it by hand on an older image, place an empty file named ssh on the boot partition.
- Ubuntu: Imager → Other general-purpose OS → Ubuntu. Desktop or Server. First login follows Ubuntu's cloud-init / first-boot notes.
- Debian: Use a Raspberry Pi Debian image built for your model, then flash with Imager or dd.
- DietPi: Download the Pi-model image from dietpi.com. Flash. First boot is a text installer for software stacks.
- Alpine: Listed under Other general-purpose OS in Imager, or follow the Alpine Raspberry Pi wiki.
- Fedora / Manjaro ARM: Download the aarch64 image for your Pi, then use Imager "Use custom" or the CLI.
sudo apt update && sudo apt full-upgrade
sudo raspi-config
# 1 System Options → Hostname, Password, Wireless
# 3 Interface Options → SSH, SPI, I2C, Serial
sudo reboot
A. pi-gen (custom Raspberry Pi OS)
Use this when you want Debian-like Raspberry Pi OS, but with your packages, user, and first-boot scripts baked in.
git clone https://github.com/RPi-Distro/pi-gen.git
cd pi-gen
# config file (example)
cat > config << 'EOF'
IMG_NAME=myproduct
RELEASE=bookworm
LOCALE_DEFAULT=en_US.UTF-8
TARGET_HOSTNAME=myproduct
FIRST_USER_NAME=admin
ENABLE_SSH=1
STAGE_LIST="stage0 stage1 stage2"
EOF
# Add extra packages in stage2/00-packages or a custom stage
sudo ./build.sh
# Output: deploy/*.imgStages in short: 0 = bootstrap, 1 = base system, 2 = Lite (CLI), 3 = desktop extras, 4 = full desktop, 5 = recommended apps. Stop at stage2 for a custom CLI image.
B. Yocto + meta-raspberrypi
Use this when the Pi is a product: you need a locked-down rootfs, a software bill of materials, and repeatable builds.
git clone git://git.yoctoproject.org/poky
git clone https://github.com/agherzan/meta-raspberrypi.git
source poky/oe-init-build-env build
# add meta-raspberrypi to conf/bblayers.conf
# in conf/local.conf:
# MACHINE = "raspberrypi5"
bitbake core-image-minimal
# Flash the .wic or .rpi-sdimg from tmp/deploy/images/C. Buildroot
Use this when the image must be small and boot fast.
git clone https://gitlab.com/buildroot.org/buildroot.git
cd buildroot
make raspberrypi5_defconfig # or raspberrypi4_defconfig
make menuconfig
make -j$(nproc)
# Flash output/images/sdcard.img
sha256sum deploy/myproduct.img
sudo rpi-imager --cli deploy/myproduct.img /dev/sdX
# Boot one board. Check SSH, app, and GPIO.
# Only then clone the card or repeat the CLI write.Real Use Cases (Problem → Cause → Effect)
1. Classroom of 20 desktop Pis
Problem: Students need a mouse, browser, and Thonny on every desk.
Cause: A Lite image has no desktop. Hand-configuring 20 cards wastes a day.
Effect: Flash Raspberry Pi OS Desktop with Imager. Set the same Wi-Fi and user in OS Customisation. Clone the first good card.
2. Home lab server in a drawer
Problem: No spare monitor. You want Docker and SSH only.
Cause: A full desktop wastes RAM and SD writes.
Effect: Flash Raspberry Pi OS Lite or Ubuntu Server. Enable SSH in Imager. ssh in and install Docker.
3. Factory kiosk that must not grow extra packages
Problem: Field units drift after apt upgrade and random desktop apps.
Cause: A general-purpose OS is not a product image.
Effect: Build with pi-gen (Debian-like) or Yocto (locked firmware). Flash the same .img on every unit. Disable unused interfaces in the build.
4. Tiny IoT node on a Zero 2 W
Problem: A desktop image will not fit well on a small card and a small CPU.
Cause: Desktop stacks assume a Pi 4/5 class board.
Effect: Use Alpine or DietPi, or a Buildroot image. Headless. SSH only.
Benefits for Teams That Ship Pi Products
| If you do this | You get |
|---|---|
| Flash a stock Lite image + SSH | Fast prototype. Good for labs and one-off gateways. |
| Use Imager customisation on every card | Known hostname, user, Wi-Fi, and SSH without a monitor. |
| Build with pi-gen | Your app and users already installed. Same image for a classroom or a kiosk fleet. |
| Build with Yocto | Reproducible firmware, license list, smaller attack surface, longer product life. |
| Build with Buildroot | Smallest card, fastest boot, simple appliance. |
| Hash and test one board first | You do not clone a broken first-boot into 200 units. |
Safety Rules (Read Once)
- Confirm the SD device with
lsblk. Wrong target wipes a PC disk. - Power the Pi after the card is seated. Do not hot-swap microSD on a running Pi.
- Use a proper power supply. Undervoltage causes random first-boot failures.
- Change the password on first login. Do not leave default credentials on a network.
- Backup a known-good card:
sudo dd if=/dev/sdX bs=4M status=progress | xz > gold.img.xz.
Installing Linux on a Raspberry Pi is writing the right image to a microSD card. Imager is the GUI path. rpi-imager --cli or dd is the CLI path. pi-gen, Yocto, and Buildroot are the custom-build path.
Start with Raspberry Pi OS Desktop if you have a screen. Start with Lite plus SSH if you do not. Build a custom image only when you will flash the same card many times or ship a product. The pictures above are the map. The command boxes are the ones to type.
References
- Alpine Linux. Raspberry Pi. https://wiki.alpinelinux.org/wiki/Raspberry_Pi
- Buildroot. The Buildroot user manual. https://buildroot.org/downloads/manual/manual.html
- Canonical. Install Ubuntu on a Raspberry Pi. https://ubuntu.com/download/raspberry-pi
- Raspberry Pi Ltd. Getting started: Install an operating system. https://www.raspberrypi.com/documentation/computers/getting-started.html
- Raspberry Pi Ltd. Raspberry Pi Imager. https://www.raspberrypi.com/software/
- RPi-Distro. pi-gen: Tool used to create Raspberry Pi OS images. https://github.com/RPi-Distro/pi-gen
- Yocto Project. meta-raspberrypi. https://github.com/agherzan/meta-raspberrypi
