rpi-imager

Write a specific image to a specific block device

$ rpi-imager --cli [path/to/image.zip] [/dev/sdX]

$ rpi-imager --cli --disable-verify [path/to/image.zip] [/dev/sdX]

$ rpi-imager --cli --sha256 [expected_hash] [path/to/image.zip] [/dev/sdX]

rpi-imager [OPTIONS...]

-v, --version
    Print version information and exit.

-h, --help
    Show this help message and exit.

--debug
    Enable debug mode.

--disable-telemetry
    Disable sending anonymous usage data.

--repo
    Use a custom image repository URI.

--json
    Output JSON listing of available images and OSes.

--country
    Pre-select country for Wi-Fi and keyboard layout settings (e.g., 'US', 'GB').

--language
    Pre-select language for the UI (e.g., 'en', 'fr').

--disable-sd-card-detect
    Disable detection of SD cards (primarily for debugging).

--disable-usb-boot-detect
    Disable detection of USB mass storage devices for boot (primarily for debugging).

--disable-pishrink
    Disable pishrink optimization for writing images (prevents shrinking the image to fit the target device).

--portable
    Run in portable mode, storing configuration files in the application directory.

--cli
    Start in CLI mode (no GUI).

--image
    Specify the local image file to write (e.g., '/path/to/raspberrypi.img').

--device
    Specify the target device to write to (e.g., '/dev/sda').

--verify
    Verify the image after writing to ensure data integrity.

--mass-storage-mode
    Put a Raspberry Pi 4/400 into USB mass storage mode for direct imaging.

--no-erase
    Do not erase the target device before writing (use with caution).

--config
    Load configuration from a specified JSON file.

--run-os
    Write a specified OS image and then boot into it (requires `--device` and `--image` or `--list-images` selection).

--customize-os
    Customize the OS before writing (requires `--device` and `--image` or `--list-images` selection).

--reconfigure
    Reconfigure an existing OS on a specified device.

--headless
    Run in headless mode (no GUI), suitable for scripting.

--quiet
    Suppress non-error output.

--no-warnings
    Do not show warnings during operation.

--disable-update-check
    Disable checking for new application updates.

--allow-unverified-download
    Allow downloading images with unverified checksums (not recommended).

--ignore-device-size-warnings
    Ignore warnings about small device sizes.

--clear-config
    Clear all saved configuration settings.

--skip-download
    Skip downloading the image and use a local file specified by `--image`.

--list-devices
    List available block devices suitable for writing and exit.

--list-images
    List available OS images from the repository and exit.

--default-settings
    Reset all application settings to their default values.

--skip-download-sha256-check
    Skip SHA256 checksum verification during image download.

--skip-image-sha256-check
    Skip SHA256 checksum verification of the downloaded image file.

--skip-network-check
    Skip checking for network connectivity.

--boot-from-usb
    Enable USB boot for compatible Raspberry Pi models (e.g., Pi 2B v1.2, Pi 3A+, 3B, 3B+).

--write-eeprom
    Write or update the EEPROM firmware on Raspberry Pi 4/400.

--reformat
    Reformat the specified device with a FAT32 partition.

--eject
    Eject the specified device after writing.

rpi-imager is the official GUI tool provided by the Raspberry Pi Foundation for easily writing operating system images to SD cards or USB drives. It simplifies the process of getting a Raspberry Pi up and running by offering a curated list of official and recommended operating systems, along with common utilities like Raspberry Pi OS (formerly Raspbian). Users can select an OS from the list, choose their target device, and then write the image. The tool handles downloading the image, flashing it, and optionally verifying the write.

While primarily a graphical application, rpi-imager also provides a powerful command-line interface (CLI), allowing for automation of image writing, pre-configuration of OS settings (like Wi-Fi and SSH), and advanced debugging. This CLI mode makes it suitable for scripting and headless operations, expanding its utility beyond typical desktop use cases.

Writing an image with rpi-imager will erase all existing data on the target device. Users must exercise extreme caution to select the correct device to avoid unintended data loss.
Requires sudo or root privileges to write to devices.
Some advanced features like --mass-storage-mode or --write-eeprom are specific to certain Raspberry Pi models and may not apply to all devices. CLI mode options require precise device paths and image files; incorrect paths can lead to critical system damage.

When using the GUI, rpi-imager offers advanced pre-configuration, allowing users to set Wi-Fi credentials, enable SSH, set hostname, timezone, and keyboard layout, and even enable telemetry, all before writing the image to the SD card. This significantly reduces post-installation setup time and can also be automated using the --config option with a JSON file.

The tool maintains an online repository of official and recommended operating systems, which it can download directly. This ensures users always get the latest and correct images without having to manually search and download from websites. The --repo option allows specifying a custom repository, enabling advanced users to access alternative image sources.

The Raspberry Pi Imager was introduced by the Raspberry Pi Foundation in 2020 as a modern, user-friendly alternative to existing imaging tools. Prior to its release, users often relied on tools like dd on Linux, Win32 Disk Imager on Windows, or balenaEtcher across platforms. The Imager was designed to streamline the process, integrate with the official image repository, and offer convenient features like pre-configuration directly within the tool, making it significantly easier for newcomers to get started with Raspberry Pi. Its continuous development adds support for new hardware and features like EEPROM updates and direct USB boot enabling.

dd(1), balena-etcher(1), fdisk(8), parted(8), mkfs(8)