Install Linux on Raspberry Pi: A Picture Guide for CLI, GUI, and Custom Builds

 

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/sdX after lsblk confirms the card.
• Custom product image: Build with pi-gen, Yocto, or Buildroot. Flash the resulting .img the same way.
• Never guess the disk. Writing to the wrong /dev/sdX wipes 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.

1. Download Imager from raspberrypi.com/software (Windows, macOS, or Linux). On Raspberry Pi OS: sudo apt install rpi-imager.
2. Open Imager. Choose Device (Pi 5, Pi 4, Zero 2 W, and so on).
3. 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.
4. Choose Storage: your microSD (check the size so you do not pick the wrong disk).
5. Open OS Customisation (gear): set hostname, username, password, Wi-Fi, locale, and enable SSH.
6. 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
    sync

If 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/*.img

Stages 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)

1. Confirm the SD device with lsblk. Wrong target wipes a PC disk.
2. Power the Pi after the card is seated. Do not hot-swap microSD on a running Pi.
3. Use a proper power supply. Undervoltage causes random first-boot failures.
4. Change the password on first login. Do not leave default credentials on a network.
5. 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

Read More