Skip to content

Instantly share code, notes, and snippets.

Last active May 16, 2024 08:38
Show Gist options
  • Save plembo/c4920016312f058209f5765cb9a3a25e to your computer and use it in GitHub Desktop.
Save plembo/c4920016312f058209f5765cb9a3a25e to your computer and use it in GitHub Desktop.
Emulating a Raspberry Pi with QEMU

Emulating a Raspberry Pi with QEMU

Goal: Emulate a Raspberry Pi with QEMU in order to run the Raspbian O/S (based on Debian Linux).

The current setup is not ideal. For one thing, the maximum RAM allowed using the "versatile-pb" firmware is 256 Mb. In addition, only the most basic peripherals, a keyboard and mouse, are supported.

A number of articles have been written on this topic. Most are outdated, and the few recent ones are missing key information.

Software Required

  1. QEMU system emulation binaries for ARM processors. On Ubuntu, qemu-system-arm.
  2. Raspbian Stretch with Desktop, disk image.
  3. Latest Debian Stretch kernel from the qemu-rpi-kernel project.


  1. Install qemu-system-arm (on Ubuntu, "sudo apt-get qemu-system-arm") to allow the emulation of devices with arm processors like the Pi.
  2. Create an emulation project directory, "~/Projects/rpitest" to hold the emulation files.
  3. Clone the qemu-rpi-kernel repo to another directory using git.
  4. Follow the instructions in the repo for building a versatile-pb.dtb file for your kernel of choice (or simply use the kernel and matching .dtb file provided by default -- currently kernel-4.9.41-stretch).
  5. Copy the kernel image and matching versatile-pb.dtb file into the project directory (e.g. "rpitest"). Rename the kernel file to "kernel-qemu".
  6. Download the latest Raspbian disk image and unzip into the project directory.
  7. Find starting sector of the image's second partition using fdisk:
$ fdisk -l 2018-06-27-raspbian-stretch.img
Disk 2018-06-27-raspbian-stretch.img: 4.5 GiB, 4823449600 bytes, 9420800 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0xbd98648d

Device                           Boot Start     End Sectors  Size Id Type
2018-06-27-raspbian-stretch.img1       8192   96663   88472 43.2M  c W95 FAT32 (LBA)
2018-06-27-raspbian-stretch.img2      98304 9420799 9322496  4.5G 83 Linux
  1. Multiply that sector number by 512 and use the result as the offset in mounting the image:
$ sudo mount 2018-06-27-raspbian-stretch.img -o offset=50331648 /mnt
  1. Edit the file to comment out its one and only line:
$ sudo vi /mnt/etc/

This will enable devices like keyboards and mice to work in the emulator.

  1. Unmount and rename the file to "rpitest.img".
$ sudo umount /mnt
$ mv 2018-06-27-raspbian-stretch.img rpitest.img
  1. Convert the raw img file to qcow2 format:
$ qemu-img convert -f raw -O qcow2 rpitest.img rpitest.qcow2

Starting the virtual machine

Copy the following code into a startup script called something like "":

#!/usr/bin/env bash
$ sudo qemu-system-arm -kernel kernel-qemu \
-cpu arm1176 -m 256 \
-M versatilepb -dtb versatile-pb.dtb \
-no-reboot \
-serial stdio \
-append "root=/dev/sda2 panic=1 rootfstype=ext4 rw" \
-hda rpitest.qcow2 \
-net nic -net user \
-net tap,ifname=vnet0,script=no,downscript=no

Login using username "pi" and password "raspberry".

Your machine should be fully functional at this point, and able to reach the Internet over the virtual network (vnet0) created along with it.

Do not update the system at this point, as the shipping image is 97% full.

Expand the disk size

To update and do useful work with the system, the root partition (/dev/sda2) will need to be expanded in size. The following steps will accomplish that.

  1. Shut down the virtual machine and run qemu-img to increase the disk size:
$ qemu-img resize rpitest.qcow2 +4G
  1. Start up the machine again and log in. Run fdisk to delete and then re-create the second partition.
$ sudo fdisk /dev/sda

The commands to run within fdisk are:

print - to show the current disk layout

(note the starting sector of the second partition)

d - to delete a partition
2 - choose partition 2
n - create a new partition
p - make it primary
2 - partition number
xxxxx - the starting sector of the original partition 2
Enter - to accept the last sector of the disk as the end of the partition
w - to write all changes to disk
  1. Complete the resizing operation by running resize2fs on the partition:
$ resize2fs /dev/sda2
  1. Run df -h to confirm the expanded disk size is recognized by the system.
Copy link

centic9 commented Jan 7, 2024

If you have Docker available, there is a nice way to do a similar thing via

docker run -it --rm -p 2222:2222 stawiski/qemu-raspberrypi-3b:2023-05-03-raspios-bullseye-arm64

See the Blog Post and the Dockerfile for details.

Copy link

mrdc commented Apr 17, 2024

I'm trying to use physical microSD from my RPi for debugging. At the moment I have an issue passing physical microSD to qemu:
-drive file=/dev/disk13,if=none,format=raw and -append "root=/dev/mmcblk0p7 rootfstype=ext4"
disk13 is the physical microSD, qemu boots the kernel, but then Kernel Panic, because it can't find root partition...

Copy link

robertkirkman commented Apr 21, 2024

Hello I am trying to find this exact guide except for Android image for Raspberry Pi instead of Raspbian and everyone is calling me stupid for wanting that. Please tell me if you know how. Specifically I want Android but specifically inside of either qemu-system-arm or qemu-system-aarch64 and specifically on an x86_64 amd64 CPU host hardware.

Copy link

plembo commented Apr 21, 2024

These (mrdc and robertkirkman) are great questions I don't have answers for. I'd encourage anyone with similar issues to reach out on the Raspberry Pi and QEMU forums, as they get a lot more traffic than these humble gists.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment