{"id":31540067,"url":"https://github.com/trinitronx/qemu-raspbian","last_synced_at":"2025-10-04T09:51:28.235Z","repository":{"id":305526796,"uuid":"1023079551","full_name":"trinitronx/qemu-raspbian","owner":"trinitronx","description":"Run Raspbian on QEMU raspi3 \u0026 raspi4 machine emulators","archived":false,"fork":false,"pushed_at":"2025-08-12T15:35:41.000Z","size":75,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-12T17:27:31.345Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trinitronx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["trinitronx","LyraPhase"],"patreon":"phasik","ko_fi":"trinitronx","liberapay":"trinitronx","polar":"lyraphase","buy_me_a_coffee":"TrinitronX","custom":["https://paypal.me/JamesCuzella"]}},"created_at":"2025-07-20T13:37:34.000Z","updated_at":"2025-08-12T15:35:42.000Z","dependencies_parsed_at":"2025-07-20T17:20:38.499Z","dependency_job_id":"462cc0cb-1dcb-4307-a6a0-eaeab3ee1b4c","html_url":"https://github.com/trinitronx/qemu-raspbian","commit_stats":null,"previous_names":["trinitronx/qemu-raspbian"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/trinitronx/qemu-raspbian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinitronx%2Fqemu-raspbian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinitronx%2Fqemu-raspbian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinitronx%2Fqemu-raspbian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinitronx%2Fqemu-raspbian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trinitronx","download_url":"https://codeload.github.com/trinitronx/qemu-raspbian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinitronx%2Fqemu-raspbian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278295840,"owners_count":25963427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-04T09:51:23.815Z","updated_at":"2025-10-04T09:51:28.229Z","avatar_url":"https://github.com/trinitronx.png","language":"Shell","funding_links":["https://github.com/sponsors/trinitronx","https://github.com/sponsors/LyraPhase","https://patreon.com/phasik","https://ko-fi.com/trinitronx","https://liberapay.com/trinitronx","https://polar.sh/lyraphase","https://buymeacoffee.com/TrinitronX","https://paypal.me/JamesCuzella","https://liberapay.com/trinitronx/donate","https://www.buymeacoffee.com/TrinitronX","https://img.shields.io/badge/dynamic/json?logo=patreon\u0026style=for-the-badge\u0026color=ffac00\u0026label=Patreon\u0026query=data.attributes.patron_count\u0026suffix=%20patrons\u0026url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F2379189","https://www.patreon.com/bePatron?u=16585899"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-configure-file\n{\n  \"required-headings\": {\n    \"headings\": [\n      \"# QEMU Raspberry Pi Emulator\",\n      \"*\",\n      \"## Features\",\n      \"*\",\n      \"## Requirements\",\n      \"*\",\n      \"## Sponsor\",\n      \"*\",\n      \"## Setup\",\n      \"*\",\n      \"## Usage\",\n      \"*\",\n      \"## Default Credentials\",\n      \"*\",\n      \"## Networking\",\n      \"*\",\n      \"## File Structure\",\n      \"*\",\n      \"## Maintenance\",\n      \"*\",\n      \"## Notes\",\n      \"*\"\n    ]\n  }\n}\n--\u003e\n# QEMU Raspberry Pi Emulator\n\nThis project provides a `Makefile` and scripts to help boot Raspberry Pi OS\n(Raspbian) in QEMU for both Raspberry Pi 3B and 4B models. It handles image\ndownloading, modification, and QEMU setup automatically.\n\n## Features\n\n- Downloads the Raspberry Pi OS Lite image\n- Converts raw `.img` to compressed `.qcow2` format\n- Resizes image to 4GiB\n- Modifies the image to:\n  - Disable USB OTG mode\n  - Enable `dwc2` module\n  - Set default `pi` user password to `raspberrypiqemu`\n  - Enable SSH with `authorized_keys` copied from your user account\n- Supports both Raspberry Pi 3B and 4B models\n  - Patches Raspberry Pi 4 device tree to enable USB controller\n  - No device tree changes needed for Raspberry Pi 3\n- Includes networking configuration\n  - Defaults to using `virbr0` from `libvirtd`\n    (user should create \u0026 start this bridge network if not already created)\n  - Option for localhost-only network with forwarded SSH port `5555`\n    If using: uncomment in the `run-*.sh` script \u0026 comment the `virbr0`.\n\n## Requirements\n\n- QEMU\n- `qemu-tools`\n- `qemu-img`\n- `nbd` kernel module\n- `dtc` (device tree compiler)\n- `wget`\n- `unxz` / `xz`\n- `bridge-utils` (for `libvirt` networking)\n- `bc` bash calculator - for floating point math support to calculate qcow2 SD\n  card image size\n\n## Sponsor\n\nIf you find this project useful and appreciate my work,\nwould you be willing to click one of the buttons below to Sponsor this project\nand help me continue?\n\n\u003c!-- markdownlint-disable MD033  --\u003e\n| Method       | Button                                                                                                                               |\n| :----------- | :----------------------------------------------------------------------------------------------------------------------------------: |\n| GitHub       | [![💖 Sponsor](https://trinitronx.github.io/assets/img/gh-button-medium.svg)](https://github.com/sponsors/trinitronx)                                                                                 |\n| Liberapay    | [![Support with Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/trinitronx/donate)                |\n| PayPal       | [![Support with PayPal](https://trinitronx.github.io/assets/img/paypal-button-medium-blue.svg)](https://paypal.me/JamesCuzella)              |\n| Ko-Fi        | [![Support with Ko-Fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/trinitronx)                                     |\n| BuyMeACoffee | [![Buy Me a Coffee](https://trinitronx.github.io/assets/img/bmc-button-medium.svg)](https://www.buymeacoffee.com/TrinitronX) |\n| Polar        | [![Support with Polar](https://trinitronx.github.io/assets/img/polar-button-medium-dark.svg)](https://polar.sh/lyraphase)                   |\n| Patreon \u003csup\u003e(_my artist page_)\u003c/sup\u003e | [![Support with Patreon](https://img.shields.io/badge/dynamic/json?logo=patreon\u0026style=for-the-badge\u0026color=ffac00\u0026label=Patreon\u0026query=data.attributes.patron_count\u0026suffix=%20patrons\u0026url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F2379189)](https://www.patreon.com/bePatron?u=16585899)                                     |\n\u003c!-- markdownlint-enable MD033  --\u003e\n\nEvery little bit is appreciated! Thank you! 🙏\n\n## Setup\n\n1. Clone this repository\n2. Run the following command:\n\n```shell\nmake prep-image\n```\n\nThe Makefile will:\n\n1. Download the Raspberry Pi OS image\n2. Convert it to `qcow2` format\n3. Ask for `sudo` password to mount the image with `qemu-nbd`\n4. Resize and modify the image\n\n## Usage\n\nTo run Raspberry Pi 3B:\n\n```shell\nmake run-raspi3\n```\n\nTo run Raspberry Pi 4B:\n\n```shell\nmake run-raspi4\n```\n\nThe prerequisites for each will be run by the `Makefile`:\n\n1. Extract necessary boot files\n2. Patch the Raspberry Pi 4 device tree (for `run-raspi4`)\n   - Decompile `.dtb` into `.dts`\n   - Patch the `.dts` to enable USB controller\n   - Recompile `.dts.patched` into `.mod.dtb`\n3. Boot the QEMU VM\n\n## Default Credentials\n\n- Username: `pi`\n- Password: `raspberrypiqemu`\n\n## Networking\n\nThe virtual machine is configured with:\n\n- Bridged networking using `virbr0`\n- SSH access (your public key is copied from `~/.ssh/authorized_keys`)\n\nTo SSH to the VM when in bridged networking mode, check the VM's IP address\nvisible in the `getty` login window.  Then run:\n\n```shell\nssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no pi@$IP_HERE\n```\n\nAn example `libvirt` network XML for the `default` network is:\n\n```xml\n\u003cnetwork\u003e\n  \u003cname\u003edefault\u003c/name\u003e\n  \u003cuuid\u003e906207b9-6fee-426d-8547-e97d3b37e0bb\u003c/uuid\u003e\n  \u003cforward mode='nat'\u003e\n    \u003cnat\u003e\n      \u003cport start='1024' end='65535'/\u003e\n    \u003c/nat\u003e\n  \u003c/forward\u003e\n  \u003cbridge name='virbr0' stp='on' delay='0'/\u003e\n  \u003cmac address='52:54:00:aa:6b:40'/\u003e\n  \u003cip address='192.168.122.1' netmask='255.255.255.0'\u003e\n    \u003cdhcp\u003e\n      \u003crange start='192.168.122.2' end='192.168.122.254'/\u003e\n    \u003c/dhcp\u003e\n  \u003c/ip\u003e\n\u003c/network\u003e\n```\n\nPlace the file contents in `default.xml` and run:\n\n```shell\nsudo virsh net-define  /tmp/default.xml\nsudo virsh net-start default\n```\n\nTo use local networking with only a forwarded port instead, comment out the\nrelated `-netdev bridge` lines from the appropriate `run-raspi*.sh` script.  For\nexample:\n\n```shell\n# Bridged via libvirt virbr0 (must be created manually)\n# -netdev bridge,id=net0,br=virbr0,helper=/usr/lib/qemu/qemu-bridge-helper\n# -device usb-net,netdev=net0\n```\n\nThen, uncomment the lines:\n\n```shell\n# localhost forwarding\n-device usb-net,netdev=net0\n-netdev user,id=net0,hostfwd=tcp::5555-:22\n```\n\nYou can then SSH to the VM with:\n\n```shell\nssh -o UserKnownHostsFile=/dev/null -p 5555 pi@127.0.1.1\n```\n\n## File Structure\n\n- `Makefile` - Main build and run script\n- `run-raspi3.sh` - QEMU run script for Raspberry Pi 3B\n- `run-raspi4.sh` - QEMU run script for Raspberry Pi 4B\n- `get-rpi-img.sh` - Script to download Raspberry Pi OS image\n- `mnt/` - Temporary mount points for image modification\n- `*.dts`, `*.dtb` - Device tree files and patches\n\n## Maintenance\n\nTo clean up:\n\n```shell\nmake clean      # Remove generated QEMU boot files\nmake clean-all  # Remove all downloaded and generated files\n```\n\nQEMU boot files include:\n\n- `kernel8.img`\n- `bcm2710-rpi-3-b.dtb`\n- `bcm2711-rpi-4-b.dtb`\n\n## Notes\n\n\u003c!-- markdownlint-disable MD046 --\u003e\n- The Raspberry Pi 4 configuration includes a device tree patch that enables\n  USB functionality\n- Both configurations include USB keyboard and mouse support\n- The image is pre-configured for headless operation with SSH enabled\n- The default password is insecure, and can be changed in the `.env.mk` file\n  - `.env.mk` file format is GNU `Makefile` syntax\n  - `USER_PASSWD` Format is: `user:passwd-hash`\n    - e.g. `pi:$6$6jHfJHU59JxxUfOS$k9natRNnu0AaeS/S9/IeVgSkwkYAjwJfGuYfnwsUoBxlNocOn.5yIdLRdSeHRiw8EWbbfwNSgx9/vUhu0NqF50`\n  - Any '`$`' characters in the password hash must be escaped by doubling them: '`$$`'\n    - This is due to the [`Makefile` syntax][1]\n    - For example, the above would become:\n\n          pi:$$6$$6jHfJHU59JxxUfOS$$k9natRNnu0AaeS/S9/IeVgSkwkYAjwJfGuYfnwsUoBxlNocOn.5yIdLRdSeHRiw8EWbbfwNSgx9/vUhu0NqF50\n\u003c!-- markdownlint-enable MD046  --\u003e\n\n[1]: https://www.gnu.org/software/make/manual/html_node/Variables-in-Recipes.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrinitronx%2Fqemu-raspbian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrinitronx%2Fqemu-raspbian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrinitronx%2Fqemu-raspbian/lists"}