RetroPie Imaging

To write a RetroPie .img.gz image to a microSD card using the dd command in Linux, you need to follow a series of steps. The dd command is a powerful utility for copying and converting files, and when used with care, it can be very effective for tasks like writing disk images to removable storage devices.

However, be cautious when using dd as it can overwrite any disk if you specify the wrong output file, leading to data loss. Always double-check the target device’s file path (/dev/sdX, where X is the letter corresponding to your device) before proceeding.

Here’s a general outline of the steps you’ll need to follow. This guide assumes that you have already downloaded the RetroPie image and that it is compressed as a .img.gz file.

  1. Locate your microSD card’s device path: Insert your microSD card into your Linux machine. You can use the lsblk command to list all block devices and identify your microSD card based on its size and partition layout. It will typically be listed as /dev/sdX or /dev/mmcblkX, where X is a letter or number corresponding to your device.

  2. Decompress the RetroPie image: Before writing the image, you need to decompress it. You can use the gunzip command if it’s a .gz file. However, to streamline the process and write the image directly without decompressing it to disk first, you can use a pipe with gunzip and dd.

     gunzip -c RetroPieImage.img.gz | sudo dd of=/dev/sdX bs=4M status=progress

    Replace RetroPieImage.img.gz with the path to your actual RetroPie image file, and /dev/sdX with the actual device path of your microSD card. The gunzip -c command decompresses the image and pipes it directly into dd.

    • gunzip -c reads the compressed file and outputs the decompressed data.
    • sudo is used because writing to a block device typically requires root permissions.
    • dd writes the input it receives to the specified output file (of=).
    • bs=4M sets the block size to 4 Megabytes to speed up the writing process.
    • status=progress shows the progress of the operation.
  3. Ensure you have the right permissions: If you encounter permission issues, ensure you’re running the command with sudo to execute it with superuser privileges.

  4. Safely eject the microSD card: After the dd command completes, it’s important to safely eject the microSD card to ensure all writes are finalized.

     sudo eject /dev/sdX

Replace /dev/sdX with the correct device identifier for your microSD card. The sync command ensures that all cached writes to the microSD card are completed.

This method directly writes the decompressed image to the microSD card in one step, saving time and disk space. Always ensure that the dd command’s of= parameter is correctly pointing to your microSD card to avoid accidentally overwriting the wrong disk.

Download img


# Dependencies check
if ! command -v jq &> /dev/null; then
    echo "jq could not be found, please install jq to continue."
    echo "sudo apt-get install jq"
    exit 1

# GitHub user/repo

# Fetch the latest release data
echo "Fetching latest RetroPie release..."
release_data=$(curl -s $RELEASE_API_URL)

# Extract the download URL for the RetroPie .img.gz file
image_url=$(echo "$release_data" | jq -r '.assets[] | select(.name | endswith(".img.gz")) | .browser_download_url')

if [[ -z $image_url ]]; then
    echo "Error: Unable to find a RetroPie .img.gz file in the latest release."
    exit 1

# Download the .img.gz file
echo "Downloading $image_url..."
wget -O retropie_latest.img.gz "$image_url"

# Prompt for the microSD card device path
echo "Enter the target microSD card device path (e.g., /dev/sdX or /dev/mmcblkX):"
read -p "Device path: " device_path

# Validate the device path
if [[ ! -e $device_path ]]; then
    echo "Error: Device path does not exist."
    exit 1

# Confirmation before proceeding
echo "This will write the image to ${device_path}. All data on ${device_path} will be lost!"
read -p "Are you sure you want to continue? (y/n): " confirmation

if [[ $confirmation != "y" ]]; then
    echo "Aborted by user."
    exit 1

# Decompress and write the image to the microSD card
echo "Writing RetroPie image to ${device_path}..."
gunzip -c retropie_latest.img.gz | sudo dd of="$device_path" bs=4M status=progress

# Finalize writes and safely eject the microSD card
echo "Synchronizing writes..."
sudo eject "$device_path"

echo "Done. You can safely remove the microSD card."