{"id":50430453,"url":"https://github.com/pacnpal/proxmox-vfio-toggle","last_synced_at":"2026-05-31T14:01:06.767Z","repository":{"id":354419080,"uuid":"1223556133","full_name":"pacnpal/proxmox-vfio-toggle","owner":"pacnpal","description":"Toggle Proxmox AMD GPU between VFIO passthrough and amdgpu/LXC modes","archived":false,"fork":false,"pushed_at":"2026-04-28T13:08:47.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T14:35:07.089Z","etag":null,"topics":["amdgpu","gpu-passthrough","homelab","lxc","proxmox","vfio"],"latest_commit_sha":null,"homepage":"https://pacnpal.github.io/proxmox-vfio-toggle/","language":"HTML","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/pacnpal.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T12:40:45.000Z","updated_at":"2026-04-28T13:08:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pacnpal/proxmox-vfio-toggle","commit_stats":null,"previous_names":["pacnpal/proxmox-vfio-toggle"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pacnpal/proxmox-vfio-toggle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fproxmox-vfio-toggle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fproxmox-vfio-toggle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fproxmox-vfio-toggle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fproxmox-vfio-toggle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pacnpal","download_url":"https://codeload.github.com/pacnpal/proxmox-vfio-toggle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pacnpal%2Fproxmox-vfio-toggle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33733754,"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-05-31T02:00:06.040Z","response_time":95,"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":["amdgpu","gpu-passthrough","homelab","lxc","proxmox","vfio"],"created_at":"2026-05-31T14:01:06.026Z","updated_at":"2026-05-31T14:01:06.756Z","avatar_url":"https://github.com/pacnpal.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# proxmox-vfio-toggle\n\n[![shellcheck](https://github.com/pacnpal/proxmox-vfio-toggle/actions/workflows/shellcheck.yml/badge.svg)](https://github.com/pacnpal/proxmox-vfio-toggle/actions/workflows/shellcheck.yml)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n![shell: bash](https://img.shields.io/badge/shell-bash-success)\n![platform: Proxmox VE](https://img.shields.io/badge/platform-Proxmox%20VE-orange)\n\nOne bash script that toggles a Proxmox host between **VFIO passthrough mode** (GPU dedicated to a VM) and **shared mode** (amdgpu loaded so the GPU can be passed to LXCs).\n\nHomepage: \u003chttps://pacnpal.github.io/proxmox-vfio-toggle/\u003e\n\n## Why this exists\n\nProxmox AMD homelabs often need to swap between dedicating the iGPU to a Windows or gaming VM and sharing it with LXCs for workloads like Ollama, Jellyfin, or Frigate. Doing it by hand means renaming modprobe files, editing the blacklist, rebuilding initramfs, and rebooting in the right order. Easy to forget a step. This script makes the switch one command.\n\n## Tested on\n\n- Proxmox VE 9.x\n- AMD Ryzen 7040 series (Phoenix1) with Radeon 780M iGPU\n- Kernel 6.17.13-1-pve\n\nShould work on any AMD GPU once the PCI IDs in your existing modprobe configs match your card.\n\n## Quick start\n\nRun as root on the Proxmox host. Default Proxmox installs log you in as root and don't ship `sudo`, so the examples below skip it. If you're on a setup where you log in as a normal user, prepend `sudo` to each command.\n\n### Run on the fly (no install)\n\nInteractive menu:\n\n```sh\ncurl -fsSL https://pacnpal.github.io/proxmox-vfio-toggle/vfio-toggle.sh | bash\n```\n\nThe script reads from `/dev/tty`, so the menu works through a pipe.\n\nDirect enable / disable:\n\n```sh\ncurl -fsSL https://pacnpal.github.io/proxmox-vfio-toggle/vfio-toggle.sh | bash -s -- --enable\ncurl -fsSL https://pacnpal.github.io/proxmox-vfio-toggle/vfio-toggle.sh | bash -s -- --disable\n```\n\n### Install for repeated use\n\n```sh\ncurl -fsSL https://pacnpal.github.io/proxmox-vfio-toggle/vfio-toggle.sh | bash -s -- --install\n```\n\nThis:\n\n- drops the script at `/usr/local/sbin/vfio-toggle.sh` (mode `0755`)\n- adds a managed block to `/etc/environment` ensuring `/usr/local/sbin` is on `PATH` for every login session, cron job, and systemd unit (skipped if it's already there)\n\nOpen a new shell after install so the updated `PATH` takes effect, then:\n\n```sh\nvfio-toggle.sh                # interactive menu\nvfio-toggle.sh --enable       # enable VFIO passthrough\nvfio-toggle.sh --disable      # disable VFIO (load amdgpu)\nvfio-toggle.sh --status       # print current mode (read-only)\n```\n\n### Uninstall\n\n```sh\ncurl -fsSL https://pacnpal.github.io/proxmox-vfio-toggle/vfio-toggle.sh | bash -s -- --uninstall\n# or, if you've installed it\nvfio-toggle.sh --uninstall\n```\n\n## What it does\n\n`--enable` (switch to VFIO passthrough):\n\n- Renames `/etc/modprobe.d/vfio.conf.disabled` back to `vfio.conf`\n- Renames `/etc/modprobe.d/vfio-off.conf.disabled` back to `vfio-off.conf`\n- Uncomments `blacklist amdgpu` in `/etc/modprobe.d/blacklist.conf`\n- Uncomments `softdep amdgpu pre: vfio-pci` in `/etc/modprobe.d/blacklist.conf`\n- Runs `update-initramfs -u`\n- Reboots after a 10 second countdown\n\n`--disable` (switch to amdgpu / LXC):\n\n- Renames `/etc/modprobe.d/vfio.conf` to `vfio.conf.disabled`\n- Renames `/etc/modprobe.d/vfio-off.conf` to `vfio-off.conf.disabled`\n- Comments out `blacklist amdgpu` in `/etc/modprobe.d/blacklist.conf`\n- Comments out `softdep amdgpu pre: vfio-pci` in `/etc/modprobe.d/blacklist.conf`\n- Runs `update-initramfs -u`\n- Reboots after a 10 second countdown\n\n`--status` reads those same files and prints `ENABLED`, `DISABLED`, or `UNKNOWN`. It does not write anything.\n\n`--install` copies the running script to `/usr/local/sbin/vfio-toggle.sh` and (if needed) appends a managed block to `/etc/environment` to put `/usr/local/sbin` on `PATH`. When invoked through `curl | bash` (so there is no on-disk source to copy from), it re-fetches the script from the Pages URL.\n\n`--uninstall` removes the script and the managed `/etc/environment` block.\n\n## Verification\n\nAfter the host comes back up, check which driver is bound to the GPU:\n\n```sh\nlspci -nnk -s \u003cpci-addr\u003e\n```\n\nFind the GPU PCI address with `lspci | grep VGA`. In VFIO mode you should see `Kernel driver in use: vfio-pci`. In shared mode you should see `Kernel driver in use: amdgpu`.\n\n## Customization\n\nThe script assumes a working VFIO setup is already in place. To adapt it:\n\n- **PCI device IDs**: hardcoded inside your existing `/etc/modprobe.d/vfio.conf`. The script does not edit IDs, it just enables or disables that file. Make sure your `vfio.conf` has the right `options vfio-pci ids=...` for your card.\n- **LXC GPU passthrough**: if you pass the GPU to a container, stop the container and remove its `dev*` entries before running `--enable`, since the GPU cannot be bound to vfio-pci while a container is holding it.\n\n## Caveats\n\n- Assumes you already have a working VFIO setup with `/etc/modprobe.d/vfio.conf` and `/etc/modprobe.d/vfio-off.conf` in place. This is not a from-scratch VFIO configurator.\n- Assumes amdgpu blacklist lines already exist in `/etc/modprobe.d/blacklist.conf`. The script toggles them on and off, it does not create them.\n- `--enable` and `--disable` reboot automatically. Do not run them on a host with workloads that cannot tolerate a reboot.\n\n## Idempotent\n\nSafe to run repeatedly. Running `--enable` when already in VFIO mode (or `--disable` when already in shared mode) is a no-op aside from the initramfs rebuild and reboot.\n\n## Development\n\nLint locally:\n\n```sh\nshellcheck --shell=bash vfio-toggle.sh\n```\n\nCI runs the same on every push to `main`.\n\nProject layout:\n\n```\n.\n├── vfio-toggle.sh            # the script\n├── README.md                 # this file\n├── index.html                # GitHub Pages landing page\n├── assets/\n│   └── logo.svg\n├── .nojekyll                 # serve files raw, no Jekyll\n└── .github/workflows/\n    └── shellcheck.yml        # CI lint\n```\n\n## License\n\n[MIT](LICENSE) © pacnpal\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpacnpal%2Fproxmox-vfio-toggle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpacnpal%2Fproxmox-vfio-toggle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpacnpal%2Fproxmox-vfio-toggle/lists"}