Can I use Raspberry Pi Imager from the command line without the GUI?

Yes. The rpi-imager package ships a CLI tool on some platforms, and the underlying image writing can be done with dd or bmaptool. However, the OS Customisation (firstrun.sh injection) is GUI-only; for headless automation look at pi-gen or cloud-init-capable images instead.

Is it safe to use the same imager.json profile across multiple Pis?

Mostly yes, with one caveat: if you set a static hostname, every Pi flashed with the same profile will have the same hostname, causing mDNS conflicts. Give each card a unique hostname in the settings, or change it post-boot with hostnamectl set-hostname.

Why does my Wi-Fi work but .local hostname resolution fail?

mDNS (.local) requires an Avahi daemon on Linux or Bonjour on Windows. Install and enable avahi-daemon on your workstation. Corporate or heavily managed networks sometimes block mDNS multicast; use the IP address directly in those cases.

Can I flash a non-Raspberry Pi image like Armbian or DietPi with OS Customisation?

Imager will write the image and offer the customisation panel, but whether the settings apply depends on whether that image's first-boot system honours firstrun.sh and the standard boot-partition markers. Armbian uses its own armbian-config mechanism; configure it after boot instead.

The image download is slow every time — is there a cache?

Yes. Imager caches downloaded images in ~/.cache/rpi-imager/ on Linux. As long as the cached file's hash matches the manifest, subsequent flashes use the local copy and are much faster.

Use Raspberry Pi Imager Like a Pro

Raspberry Pi Imager has grown well beyond a simple "click and flash" tool. The built-in advanced options let you pre-configure SSH, Wi-Fi credentials, a hostname, locale, and a non-root user before the card ever touches your Pi. Done right, you can boot straight into a headless, network-connected system with no HDMI, keyboard, or post-install fiddling required. This guide covers the full workflow: picking the right image, unlocking every advanced option, writing the card safely, verifying the result, and saving a reusable profile so your next flash takes thirty seconds.

Install Raspberry Pi Imager

Raspberry Pi Imager 1.8+ is required for all features shown here. Older versions lack the current advanced-options layout.

Debian / Ubuntu

sudo apt update && sudo apt install rpi-imager

If the repo version is older than 1.8, grab the official .deb directly:

wget https://downloads.raspberrypi.org/imager/imager_latest_amd64.deb
sudo apt install ./imager_latest_amd64.deb

Fedora / RHEL family

sudo dnf install rpi-imager

Arch Linux

sudo pacman -S rpi-imager

macOS / Windows

Download the installer from raspberrypi.com/software. The workflow below is identical across platforms.

Step 1 — Choose Your Device and OS

Launch rpi-imager. The interface presents three buttons in sequence: Raspberry Pi Device, Operating System, and Storage.

Click Raspberry Pi Device and select your exact model (Pi 4, Pi 5, Pi Zero 2 W, etc.). This filters the OS list to images that are actually compatible.
Click Operating System. The top-level choices are:
- Raspberry Pi OS (64-bit) — recommended for Pi 3 and later; full desktop.
- Raspberry Pi OS Lite (64-bit) — no desktop, ideal for headless servers.
- Raspberry Pi OS (Legacy) — 32-bit Bullseye for older hardware or software that requires it.
- Other general-purpose OS — Ubuntu Server, Ubuntu Desktop, and community images live here.
- Use custom — flash any local .img, .img.xz, or .iso file.

For a headless home server or cluster node, Raspberry Pi OS Lite (64-bit) is the right default. It boots faster, consumes less RAM, and has no display-manager overhead.

Step 2 — Select Storage

Click Storage and pick your microSD card or USB drive. Imager only shows removable block devices, reducing the risk of overwriting the wrong disk. Double-check the device size anyway — a 32 GB card is hard to confuse, but a 128 GB card and an external SSD can look identical in the list.

Minimum card recommendations: 8 GB for Lite, 16 GB for the full desktop image. Use at least a Class 10 / A1-rated card; A2 is noticeably faster for random I/O.

Step 3 — Open Advanced Options (OS Customisation)

After selecting device, OS, and storage, click Next. Imager will ask: "Would you like to apply OS customisation settings?" Click Edit Settings. This opens the OS Customisation panel — the most important part of this guide.

General tab

Set hostname: Give the Pi a unique mDNS name (e.g., pihole, mediaserver). It will be reachable at hostname.local on most networks without any DNS setup.
Set username and password: The default pi user no longer exists in current images. Set a strong password here. The username can be anything.
Configure wireless LAN: Enter your SSID and passphrase. Set the Wireless LAN country to your ISO 3166-1 alpha-2 code (e.g., US, GB, DE). Getting this wrong causes the Wi-Fi radio to operate outside legal channels and may prevent it from associating at all.
Set locale settings: Timezone (e.g., America/New_York) and keyboard layout. Setting these here avoids the first-boot wizard entirely.

Services tab

Enable SSH: Turn this on for any headless deployment. Choose Use password authentication for simplicity, or Allow public-key authentication only for better security.
Authorised keys: If you chose key-based auth, paste your public key here. Retrieve it with cat ~/.ssh/id_ed25519.pub (or id_rsa.pub). The key is written to /home/username/.ssh/authorized_keys on first boot.

Options tab

Play sound when finished: Useful when flashing multiple cards in a noisy environment.
Eject media when finished: Keeps it on by default — safe to leave enabled.
Enable telemetry: Sends anonymous usage data to Raspberry Pi Ltd. Disable if that matters to you.

Step 4 — Save a Persistent Custom Profile

Raspberry Pi Imager stores your customisation settings in a JSON file so you do not have to re-enter them every time. Click Save at the bottom of the OS Customisation panel before clicking Yes to apply.

The config file lives at:

# Linux
~/.config/Raspberry Pi/imager.json

# macOS
~/Library/Application\ Support/Raspberry\ Pi/imager.json

# Windows
%APPDATA%\Raspberry Pi\imager.json

Back this file up if you manage many Pis with the same base config. You can also maintain multiple named copies and swap them in before launching Imager.

Step 5 — Write and Verify

With settings saved, click Yes on the "apply customisation" prompt, then confirm the write warning. Imager will:

Download the image (or read from cache at ~/.cache/rpi-imager/ on Linux).
Write the image to the card.
Run a SHA-256 verification pass automatically.

Do not skip verification. A silent write error is far more frustrating to debug than the sixty-second verify step. Imager confirms success with a completion dialog; any mismatch produces a clear error — re-flash if that happens.

Step 6 — Flash a Custom / Third-Party Image

Select Operating System → Use custom to flash any local image file. Supported formats: .img, .img.xz, .img.gz, .zip (containing a single .img). The OS Customisation panel still appears and will attempt to inject the firstrun.sh script and write ssh / wpa_supplicant.conf to the boot partition — this works correctly for any Raspberry Pi OS derivative and Ubuntu Server for Pi. Non-Pi images (e.g., a raw Armbian build) will show customisation options but may not apply them, since those images use different first-boot mechanisms.

Verify the Boot Partition After Flashing

Before inserting the card into the Pi, re-mount it and confirm the customisation was written:

# Check SSH is enabled (a file named 'ssh' triggers sshd on first boot)
ls /media/$USER/bootfs/ssh

# Confirm firstrun script exists (carries hostname, user, Wi-Fi setup)
ls /media/$USER/bootfs/firstrun.sh

# Verify cmdline.txt references firstrun.sh
cat /media/$USER/bootfs/cmdline.txt

The mount point name may be boot or bootfs depending on OS version. You should see systemd.run=/boot/firstrun.sh appended to cmdline.txt — that is how the setup script is executed exactly once on first boot.

First Boot and SSH Connection

Insert the card, power the Pi, and wait roughly 60–90 seconds for first-boot provisioning to complete (it reboots once automatically after running firstrun.sh). Then connect:

ssh username@hostname.local

If mDNS is not working on your network, find the IP from your router's DHCP table and connect directly:

ssh username@192.168.1.x

Troubleshooting

SSH refused / connection timed out

Wait the full 90 seconds — first-boot provisioning triggers a reboot and sshd only starts after that second boot completes. If it still fails, re-mount the card and confirm bootfs/ssh exists. Re-flash if missing.

Wi-Fi not connecting

The most common cause is a wrong Wireless LAN country code. Re-flash with the correct code. Also confirm the SSID is 2.4 GHz if using a Pi Zero W (it has no 5 GHz radio) or Pi 3 (5 GHz support varies by model).

Hostname not resolving via .local

mDNS resolution requires Avahi (Linux) or Bonjour (macOS/Windows) on the connecting machine. On Linux, install and enable it:

sudo apt install avahi-daemon
sudo systemctl enable --now avahi-daemon

Custom image — settings not applied

Third-party images that do not use the firstrun.sh mechanism will not pick up Imager's customisation. Configure those images manually post-boot, or use cloud-init if the image supports it.