{"id":25735954,"url":"https://github.com/small-hack/smol-gpu-passthrough","last_synced_at":"2026-06-09T22:31:31.215Z","repository":{"id":144678977,"uuid":"585672772","full_name":"small-hack/smol-gpu-passthrough","owner":"small-hack","description":"Set up GPU passthrough on Debain \u0026 Ubuntu hosts.","archived":false,"fork":false,"pushed_at":"2024-06-16T09:07:57.000Z","size":103,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-26T05:36:40.419Z","etag":null,"topics":["gpu-acceleration","gpu-passthrough","iommu"],"latest_commit_sha":null,"homepage":"","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/small-hack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2023-01-05T19:21:06.000Z","updated_at":"2024-06-16T09:08:00.000Z","dependencies_parsed_at":"2025-02-26T05:34:37.088Z","dependency_job_id":"9d7ae587-9fd0-451d-91de-0124c33b79cd","html_url":"https://github.com/small-hack/smol-gpu-passthrough","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/small-hack/smol-gpu-passthrough","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fsmol-gpu-passthrough","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fsmol-gpu-passthrough/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fsmol-gpu-passthrough/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fsmol-gpu-passthrough/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/small-hack","download_url":"https://codeload.github.com/small-hack/smol-gpu-passthrough/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/small-hack%2Fsmol-gpu-passthrough/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34129072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","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":["gpu-acceleration","gpu-passthrough","iommu"],"created_at":"2025-02-26T05:34:26.670Z","updated_at":"2026-06-09T22:31:31.206Z","avatar_url":"https://github.com/small-hack.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚠️ Notice of migration and AI policy\n\nThis repo now lives at https://codeberg.org/small-hack/smol-gpu-passthrough\n\nYou may not ingest this repo using LLMs or AI. AI agents are forbidden.\n\n# GPU-Passthrough using OVMF + VFIO/IOMMU\n\nSet up GPU passthrough on Debain \u0026amp; Ubuntu hosts.\n\n## CAUTION\n\n- This script will modify `/etc/default/grub` and could cause your machine to enter and un-recoverable state. Do not run this script on a machine you are not willing to re-image.\n\n- This script has only been tested on Intel and Nvidia hardware. \n\n- Do not install your GPU drivers on the host machine unless you are using a laptop with Nvidia Prime/Optimus.\n\n## Quickstart\n\n1. Enable IOMMU in grub\n\n    ```bash\n    # /etc/default/grub\n    GRUB_DEFAULT=0\n    GRUB_TIMEOUT=5\n    GRUB_DISTRIBUTOR=`lsb_release -i -s 2\u003e /dev/null || echo Debian`\n    GRUB_CMDLINE_LINUX_DEFAULT=\"quiet preempt=voluntary iommu=pt amd_iommu=on intel_iommu=on\"\n    GRUB_CMDLINE_LINUX=\"\"\n    ```\n2. Update grub and reboot\n\n    ```bash\n    sudo update-grub\n    sudo reboot now\n    ``` \n    \n3. Download and run `setup.sh`\n\n    ```bash\n    # Set up GPU passthrough for your distro\n    # ubuntu\n    bash setup.sh full NVIDIA ubuntu\n    # debian\n    bash setup.sh full NVIDIA debian\n    \n    # Reset \n    bash setup.sh reset\n    ```\n\n4. Reboot the machine\n\n\n5. You are now ready to present the GPU to your VMM. An example using QEMU:\n\n    ```bash\n    \u003e lspci |grep -ai nvidia |grep VGA | awk '{print $1}'\n    \u003e 02:00.0\n    ```\n    \n    ```bash\n    sudo qemu-system-x86_64 -machine accel=kvm,type=q35 \\\n        -cpu host,kvm=off,hv_vendor_id=null \\\n        -smp 4,sockets=1,cores=2,threads=2,maxcpus=4 \\\n        -m 8G \\\n        -vga virtio -serial stdio -parallel none \\\n        -device vfio-pci,host=02:00.0,multifunction=on,x-vga=on \\\n        -netdev user,id=network0,hostfwd=tcp::1234-:22 \\\n        -device virtio-net-pci,netdev=network0 \\\n        -drive if=virtio,format=qcow2,file=disk.qcow2,index=1,media=disk \\\n        -drive if=virtio,format=raw,file=seed.img,index=0,media=disk \\\n        -bios /usr/share/ovmf/OVMF.fd \\\n        -usbdevice tablet \\\n        -vnc 192.168.50.100:0\n    ```\n\n## Slow-Start\n\nThis is a long-form explanation of the `setup.sh` script that explains the underlying automation process. It is assumed that the reader has a fresh install of Debian 12 (no gui), or Ubuntnu Server and is using a NVIDIA GPU and an x86_64 Intel CPU. \n\n- AMD devices have NOT been tested. \n- ARM devices have NOT been tested.\n\n### Enabling IOMMU\n\n - Enable IOMMU by changing the `GRUB_CMDLINE_LINUX_DEFAULT` line in your `/etc/default/grub` file to the following:\n\n   ```bash\n    GRUB_CMDLINE_LINUX_DEFAULT=\"quiet preempt=voluntary iommu=pt amd_iommu=on intel_iommu=on\"\n    ```\n    Then run `sudo update-grub`.\n    \n    \u003e The `preempt` option is also enabled here to reduce boot-times for systems with large amounts of RAM.\n    \n - Install dependancies \n\n   ```bash\n   sudo apt-get -y install \\\n         qemu-kvm \\\n         bridge-utils \\\n         virtinst \\\n         ovmf \\\n         qemu-utils \\\n         cloud-image-utils \\\n         curl\n   ```\n\n - Reboot (Required)\n\n\n### Gathering IOMMU data\n\n  Now that IOMMU is enabled we can look for devices in `/sys/kernel/iommu_groups`. The formatting is awful by default so here is a small script to list it in a more readable way courtesy of leduccc.medium.com \n\n   - [SOURCE](https://leduccc.medium.com/simple-dgpu-passthrough-on-a-dell-precision-7450-ebe65b2e648e)\n   \n   ```bash\n   curl -fsSL \"https://raw.githubusercontent.com/cloudymax/Scrap-Metal/main/virtual-machines/host-config-resources/iommu-groups.sh\" | /bin/bash\n   ```\n   \n   The output of the above script will list all IOMMU groups, as well as the PCI ID, a description of each of your PCI devices, and at the end of the line is the IOMMU ID that we require. You will need to find the group number that your graphics card belongs to, and the IOMMU IDs of each item in that group. In the case of the example blow, the IOMMU IDs we need are `10de:1f08`, `10de:10f9`, `10de:1ada`, and `10de:1adb`.\n\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to expand\u003c/summary\u003e\n   \n   ```bash\n   IOMMU Group 0 00:02.0 VGA compatible controller [0300]: Intel Corporation RocketLake-S GT1 [UHD Graphics 750] [8086:4c8a] (rev 04)\n   IOMMU Group 1 00:00.0 PCI bridge [0604]: Intel Corporation Device [8086:4c43] (rev 01)\n   IOMMU Group 2 00:01.0 PCI bridge [0604]: Intel Corporation Device [8086:4c01] (rev 01)\n   IOMMU Group 3 00:04.0 Signal processing controller [1180]: Intel Corporation Device [8086:4c03] (rev 01)\n   IOMMU Group 4 00:08.0 System peripheral [0880]: Intel Corporation Device [8086:4c11] (rev 01)\n   IOMMU Group 5 00:12.0 Signal processing controller [1180]: Intel Corporation Comet Lake PCH Thermal Controller [8086:06f9]\n   IOMMU Group 6 00:14.0 USB controller [0c03]: Intel Corporation Comet Lake USB 3.1 xHCI Host Controller [8086:06ed]\n   IOMMU Group 6 00:14.2 RAM memory [0500]: Intel Corporation Comet Lake PCH Shared SRAM [8086:06ef]\n   IOMMU Group 7 00:14.3 Network controller [0280]: Intel Corporation Comet Lake PCH CNVi WiFi [8086:06f0]\n   IOMMU Group 8 00:15.0 Serial bus controller [0c80]: Intel Corporation Comet Lake PCH Serial IO I2C Controller #0 [8086:06e8]\n   IOMMU Group 9 00:16.0 Communication controller [0780]: Intel Corporation Comet Lake HECI Controller [8086:06e0]\n   IOMMU Group 10 00:17.0 SATA controller [0106]: Intel Corporation Comet Lake SATA AHCI Controller [8086:06d2]\n   IOMMU Group 11 00:1b.0 PCI bridge [0604]: Intel Corporation Comet Lake PCI Express Root Port #21 [8086:06ac] (rev f0)\n   IOMMU Group 12 00:1c.0 PCI bridge [0604]: Intel Corporation Device [8086:06bc] (rev f0)\n   IOMMU Group 13 00:1f.0 ISA bridge [0601]: Intel Corporation H470 Chipset LPC/eSPI Controller [8086:0684]\n   IOMMU Group 13 00:1f.3 Audio device [0403]: Intel Corporation Device [8086:f1c8]\n   IOMMU Group 13 00:1f.4 SMBus [0c05]: Intel Corporation Comet Lake PCH SMBus Controller [8086:06a3]\n   IOMMU Group 13 00:1f.5 Serial bus controller [0c80]: Intel Corporation Comet Lake PCH SPI Controller [8086:06a4]\n   IOMMU Group 14 02:00.0 VGA compatible controller [0300]: NVIDIA Corporation TU106 [GeForce RTX 2060 Rev. A] [10de:1f08] (rev a1)\n   IOMMU Group 14 02:00.1 Audio device [0403]: NVIDIA Corporation TU106 High Definition Audio Controller [10de:10f9] (rev a1)\n   IOMMU Group 14 02:00.2 USB controller [0c03]: NVIDIA Corporation TU106 USB 3.1 Host Controller [10de:1ada] (rev a1)\n   IOMMU Group 14 02:00.3 Serial bus controller [0c80]: NVIDIA Corporation TU106 USB Type-C UCSI Controller [10de:1adb] (rev a1)\n   IOMMU Group 15 03:00.0 Non-Volatile memory controller [0108]: ADATA Technology Co., Ltd. XPG SX8200 Pro PCIe Gen3x4 M.2 2280 Solid State Drive [1cc1:8201] (rev 03)\n   ```\n\u003c/details\u003e\n\n\n### Enable VFIO-PCI and disable conflicting kernel modules\n\nIn order to pass control of the GPU to the VM we will need to hand over control of the PCI devices to VFIO. This only works though if VFIO has control of ALL items in the GPU's IOMMU group.\n\n   - edit/create `/etc/initramfs-tools/modules` (Debian), or `/etc/initram-fs/modules` (Ubuntu) to include the following:\n   \n      ```bash\n      vfio\n      vfio_iommu_type1\n      vfio_pci\n      vfio_virqfd\n      options vfio-pci ids=\u003csomeID,someOtherID\u003e\n      ```\n   \n   - edit/create `/etc/modprobe.d/blacklist.conf` (Debian), or `/etc/modprobe.d/local.conf` (Ubuntu)\n      \n      ```bash\n      options vfio-pci ids=\u003csomeID,someOtherID\u003e\n      ```\n      \n   - edit the `GRUB_CMDLINE_LINUX_DEFAULT` line of your `/etc/default/grub` file again to the following:\n   \n      ```bash\n      GRUB_CMDLINE_LINUX_DEFAULT=\"quiet preempt=voluntary iommu=pt amd_iommu=on intel_iommu=on vfio-pci.ids=\u003c\u003csomeID,someOtherID\u003e rd.driver.pre=vfio-pci video=efifb:off kvm.ignore_msrs=1 kvm.report_ignored_msrs=0\"\n      ```\n  \n   - Now run `sudo update-grub`, `sudo update-initramfs -u`, `sudo depmod -ae` and then reboot. (Required)\n\n\n### Disabling conflicting kernel drivers\n\nA common issue I have seen others encounter with this process is that VFIO is not given control of all devices in the GPU's IOMMU group. Most often this is due to the xhci_hcd USB module retaining control of the GPU's USB controller. \n\n  \u003e As per the [Debian Wiki](https://wiki.debian.org/KernelModuleBlacklisting) - to disable this kernel module, or any other you can:\n  \u003e \n  \u003e - Create a file `/etc/modprobe.d/\u003cmodulename\u003e.conf` containing `blacklist \u003cmodulename\u003e`.\n  \u003e - Run `sudo depmod -ae` as root\n  \u003e - Recreate your initrd with `sudo update-initramfs -u`\n \nSo I will now edit/create `/etc/modprobe.d/xhci_hcd.conf` to contain\n      \n  ```bash\n  blacklist xhci_hcd\n  ```\n   \nThen I will run `sudo update-initramfs -u`, `sudo depmod -ae` and reboot. (Required)\n\n\n### Verify VFIO control over PCI Devices\n\n   After your machien reboots, run `lspci -nnk` to show which kernel driver has control over each PCI device. All devices should show `vfio-pci` as the kernel driver in use. If not, you will need to repeat the previous steps to disable that driver.\n\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to expand\u003c/summary\u003e\n   \n   ```bash\n   02:00.0 VGA compatible controller [0300]: NVIDIA Corporation TU106 [GeForce RTX 2060 Rev. A] [10de:1f08] (rev a1)\n\t   Subsystem: ASUSTeK Computer Inc. TU106 [GeForce RTX 2060 Rev. A] [1043:86f0]\n\t   Kernel driver in use: vfio-pci\n\t   Kernel modules: nouveau\n   02:00.1 Audio device [0403]: NVIDIA Corporation TU106 High Definition Audio Controller [10de:10f9] (rev a1)\n\t   Subsystem: ASUSTeK Computer Inc. TU106 High Definition Audio Controller [1043:86f0]\n\t   Kernel driver in use: vfio-pci\n\t   Kernel modules: snd_hda_intel\n   02:00.2 USB controller [0c03]: NVIDIA Corporation TU106 USB 3.1 Host Controller [10de:1ada] (rev a1)\n\t   Subsystem: ASUSTeK Computer Inc. TU106 USB 3.1 Host Controller [1043:86f0]\n\t   Kernel driver in use: vfio-pci\n\t   Kernel modules: xhci_pci\n   02:00.3 Serial bus controller [0c80]: NVIDIA Corporation TU106 USB Type-C UCSI Controller [10de:1adb] (rev a1)\n\t   Subsystem: ASUSTeK Computer Inc. TU106 USB Type-C UCSI Controller [1043:86f0]\n\t   Kernel driver in use: vfio-pci\n   ```\n\u003c/details\u003e\n\nAt this point your host machine is ready to create GPU accelerated guest VMs.\n\n\n## Resources and Help\n\nThis is not a new development or an original work. It's bits and pieces of knowledge from people much smarter than myself that have been cut-and-pasted into a slightly easier-to-use format.\n\nGPU Passthrough resources:\n\n- [GPU Passthrough on a Dell Precision 7540 and other high end laptops](https://leduccc.medium.com/simple-dgpu-passthrough-on-a-dell-precision-7450-ebe65b2e648e) - leduccc\n\n- [Improving the performance of a Windows Guest on KVM/QEMU](https://leduccc.medium.com/improving-the-performance-of-a-windows-10-guest-on-qemu-a5b3f54d9cf5) - leduccc\n\n- [Comprehensive guide to performance optimizations for gaming on virtual machines with KVM/QEMU and PCI passthrough](https://mathiashueber.com/performance-tweaks-gaming-on-virtual-machines/) - Mathias Hüber\n\n- [Virtual machines with PCI passthrough on Ubuntu 20.04, straightforward guide for gaming on a virtual machine](https://mathiashueber.com/pci-passthrough-ubuntu-2004-virtual-machine/) - Mathias Hüber\n\n- [gpu-virtualization-with-kvm-qemu](https://medium.com/@calerogers/gpu-virtualization-with-kvm-qemu-63ca98a6a172) - Cale Rogers\n\n- [Faster Virtual Machines on Linux Hosts with GPU Acceleration](https://adamgradzki.com/2020/04/06/faster-virtual-machines-linux/) - Adam Gradzki\n\n  |Author| Year |CPU | GPU | OS | modules method | pci-ids medthod |\n  |--|--|--|--|--|--|--|\n  | Leducc | 2020 | Intel | Nvidia | Manjaro |/etc/mkinitcpio.conf |GRUB_CMDLINE_LINUX_DEFAULT| \n  | Mathias Hüber | 2021 | AMD | Nvidia | Ubuntu 18.04 \u0026 20.04 | /etc/initramfs-tools/modules|GRUB_CMDLINE_LINUX_DEFAULT and /etc/initramfs-tools/scripts/init-top/vfio.sh|\n  | Cale Rogers | 2016 | Intel | Nvidia | Ubuntu 16.04 | GRUB_CMDLINE_LINUX and /etc/initram-fs/modules|/etc/modprobe.d/local.conf|\n  | Adam Gradzki | 2020 | Intel | Intel | ?? | ---| created by i915-GVTg_V5_2 |\n\n## Cloud-Init Resources:\n\n- [My Magical Adventure With cloud-init](https://christine.website/blog/cloud-init-2021-06-04) - Xe Iaso\n\n## Hypervisor Resources:\n\n- [A Study of Performance and Security Across the Virtualization Spectrum](https://repository.tudelft.nl/islandora/object/uuid:34b3732e-2960-4374-94a2-1c1b3f3c4bd5/datastream/OBJ/download) - Vincent van Rijn\n\n- [virtualization-hypervisors-explaining-qemu-kvm-libvirt](https://sumit-ghosh.com/articles/virtualization-hypervisors-explaining-qemu-kvm-libvirt/) by Sumit Ghosh\n\nKubernetes/Docker Resources:\n\n- [Schedule GPUs in K8s](https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/#deploying-amd-gpu-device-plugin)\n\n- [NVIDIA Container Toolkit install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)\n\nKernel Options Docs:\n\n- [Linux Kernel Params](https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html)\n\n- [Intel i915 Driver Options](https://www.kernel.org/doc/html/latest/gpu/i915.html?highlight=vfio%20pci)\n\n- [PCI VFIO options](https://www.kernel.org/doc/html/latest/driver-api/vfio-pci-device-specific-driver-acceptance.html?highlight=vfio%20pci)\n\n- [KMV Ignore MSRs](https://www.kernel.org/doc/html/latest/virt/kvm/x86/msr.html?highlight=kvm%20ignore%20msrs)\n\n- [root device (rd) kernel options](https://man7.org/linux/man-pages/man7/dracut.cmdline.7.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmall-hack%2Fsmol-gpu-passthrough","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmall-hack%2Fsmol-gpu-passthrough","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmall-hack%2Fsmol-gpu-passthrough/lists"}