{"id":50684497,"url":"https://github.com/mateussouzaweb/libvirt-hooks","last_synced_at":"2026-06-08T21:33:53.029Z","repository":{"id":361293495,"uuid":"1253914129","full_name":"mateussouzaweb/libvirt-hooks","owner":"mateussouzaweb","description":"Custom scripts for KVM / QEMU based on libvirt hooks","archived":false,"fork":false,"pushed_at":"2026-05-30T00:17:04.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-30T02:09:41.407Z","etag":null,"topics":["gpu-passthrough","hooks","kvm","libvirt","libvirt-hooks","qemu","virtual-machine","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mateussouzaweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T00:03:25.000Z","updated_at":"2026-05-30T00:17:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mateussouzaweb/libvirt-hooks","commit_stats":null,"previous_names":["mateussouzaweb/libvirt-hooks"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mateussouzaweb/libvirt-hooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateussouzaweb%2Flibvirt-hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateussouzaweb%2Flibvirt-hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateussouzaweb%2Flibvirt-hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateussouzaweb%2Flibvirt-hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateussouzaweb","download_url":"https://codeload.github.com/mateussouzaweb/libvirt-hooks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateussouzaweb%2Flibvirt-hooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34082130,"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-08T02:00:07.615Z","response_time":111,"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-passthrough","hooks","kvm","libvirt","libvirt-hooks","qemu","virtual-machine","virtualization"],"created_at":"2026-06-08T21:33:52.141Z","updated_at":"2026-06-08T21:33:53.019Z","avatar_url":"https://github.com/mateussouzaweb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Libvirt Hooks for KVM / QEMU\n\nCustom scripts for KVM / QEMU based on [libvirt hooks](https://libvirt.org/hooks.html).\n\n## Overview\n\nYou may already know KVM / QEMU with libvirt and how hooks can be used to run more powerful and advanced virtual machines.\n\nThis project is a set of hooks for the missing pieces of libvirt for homelab and desktop users, with deeper automation and action by parsing virtual machine details and acting where libvirt doesn't touch. With this script, you may not need to set up hooks for your desktop; just run the VM and let the script do the hard work for you automatically.\n\n## Features\n\n**- Real hook automation**\\\nEverything is fully automated. Since the script can understand aspects of your environment, it can detect additional actions to perform for you when running virtual machines with KVM / QEMU.\n\n**- Handling for main GPU passthrough**\\\nWhen you have only one GPU in your system, the hook will automatically free the GPU for VFIO usage by stopping the current display manager and unbinding virtual consoles or framebuffers. It also manages the resizable BAR and releases GPU drivers when starting and stopping the virtual machine.\n\n**- Supports secondary GPU passthrough**\\\nThe script also works with systems based on multiple GPUs.\n\n**- CPU core isolation**\\\nAutomatically detects which CPU cores should be used by the virtual machine and by the host system in order to isolate cores and increase performance.\n\n**- CPU scaling governor**\\\nEnable additional performance by setting the correct scaling governor when virtual machines are powered on.\n\n**- USB passthrough**\\\nFrees USB devices for passthrough, and by combining it with udev rules, automatically passes through USB devices to a running virtual machine for easier access.\n\n**- Environment debugging**\\\nIncludes commands to inspect the system and provide highly detailed information such as PCI devices, CPU, GPUs, USBs, Display Manager, Virtual Consoles, Framebuffers, etc.\n\n**- Consistent logging**\\\nAll performed actions are logged to the host message bus for easier debugging. Messages can be read with the `dmesg` command along with other system actions.\n\n**- Extra scripting support**\\\nYou can use this hook for most of the automation and combine with smaller custom ones to perform additional tasks if needed.\n\n## Installation\n\nGo to the project RELEASES page and download the latest version of the script for your Linux architecture:\n\n```bash\n# Download compiled binary\nREPOSITORY=\"https://github.com/mateussouzaweb/libvirt-hooks\"\nsudo wget $REPOSITORY/releases/latest/download/qemu-amd64 -O ./qemu\n\n# Move binary to correct location\nsudo mv qemu /etc/libvirt/hooks/qemu\nsudo chmod +x /etc/libvirt/hooks/qemu\n\n# Install udev rules\nsudo /etc/libvirt/hooks/qemu install\n```\n\n**That is it!**\\\nNow configure your virtual machine details on KVM / QEMU and let this script automate actions for you, such as passing through your GPU or setting the CPU scaling governor.\n\n## Extra Scripts\n\nIf you need to perform additional actions with QEMU hooks in Libvirt, you should put your custom scripts into the ``/etc/libvirt/hooks/qemu.d/`` folder.\nThis folder is already officially supported by libvirt and supports multiple scripts. For example:\n\n- ``/etc/libvirt/hooks/qemu.d/start.sh`` - script to run before VMs start.\n- ``/etc/libvirt/hooks/qemu.d/stop.sh`` - script to run after VMs have been stopped.\n\nSee the [official documentation](https://libvirt.org/hooks.html) for more details.\n\n## Building\n\nThis project was developed in Go and provides a single binary file to handle all aspects of desktop virtualization for you.\n\nIf you want to manually build the project, there is a build script here too. Simply run the script and it will build binaries for both AMD64 and ARM64:\n\n```bash\ngo run build.go\n```\n\nThen install the binary to the target destination:\n\n```bash\n# Move binary\nchmod +x bin/qemu-$(ARCH); \\\nsudo mv bin/qemu-$(ARCH) /etc/libvirt/hooks/qemu\n\n# Install udev rules\nsudo /etc/libvirt/hooks/qemu install\n```\n\n## Developing \u0026 Debugging\n\nIf you want to increase the features of the script or debug the output, here are a few tips:\n\n```bash\n# Run as sudo\nsudo su\ncd /etc/libvirt/hooks/\n\n# Basic commands\n./qemu help\n./qemu install\n./qemu uninstall\n\n# Environment debugging\n./qemu state | jq .\n\n# Udev USB commands\n# Pass details as environment variables like udev does\nACTION=\"add\" BUSNUM=\"\" DEVNUM=\"\" PRODUCT=\"\" ./qemu usb\n\n# Libvirt hooks for VM actions\n./qemu $VM prepare begin -\n./qemu $VM release end - \n\n# Check system logs\nsudo dmesg\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateussouzaweb%2Flibvirt-hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateussouzaweb%2Flibvirt-hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateussouzaweb%2Flibvirt-hooks/lists"}