"description":"Move an already-assigned GPU between VM mode (vfio-pci) and LXC mode (native driver) on a Proxmox host. ProxMenux detects the current binding, prompts per-workload conflict policies, handles orphan audio cleanup, and rebuilds initramfs only when needed."
"description":"Move an assigned GPU between VM passthrough and LXC sharing. ProxMenux manages the host driver binding, VFIO configuration, module settings and initramfs, and asks how to handle affected guests. Review those choices and verify the resulting configuration after reboot.",
"body":"A GPU on a Proxmox host lives in one of two modes: bound to <code>vfio-pci</code> (reserved for a VM) or bound to its native driver <em>(i915 / amdgpu / nvidia)</em> so the host + LXCs can share it. <strong>Switch GPU Mode</strong> flips between those two without you having to hand-edit <code>vfio.conf</code>, manage blacklists, or remember which VM / LXC lines point to the card. It also warns you cleanly if a workload still references the GPU so you don't end up with a broken VM at boot."
},
"graphics":{
"lxcTitle":"Ready for LXC containers",
"lxcDesc":"Native driver active",
"vmTitle":"Ready for VM passthrough",
"vmDesc":"VFIO-PCI driver active"
},
"when":{
"heading":"When should I use this?",
"intro":"Use this script when a GPU is <strong>already assigned</strong> and you want to move it:",
"headerSituation":"Situation",
"headerUse":"Use this page?",
"rows":[
{
"situation":"GPU is free — never assigned. Want to give it to a VM.",
"useRich":"No — use <vmLink>Add GPU to VM</vmLink>"
},
{
"situation":"GPU is free — never assigned. Want to give it to an LXC.",
"useRich":"No — use <lxcLink>Add GPU to LXC</lxcLink>"
},
{
"situationRich":"GPU is in a VM via <code>vfio-pci</code>, I want to use it from an LXC instead.",
"useRich":"<strong>Yes — this page.</strong>"
},
{
"situation":"GPU is shared with an LXC, I want to dedicate it to a VM.",
"useRich":"<strong>Yes — this page.</strong>"
},
{
"situation":"I just want to completely unbind a GPU from everything.",
"use":"LXC mode restores host-driver ownership; the VM conflict policy can remove hostpci entries, but LXC device entries must be removed separately. This does not leave the GPU unbound from every driver."
"assigned":"<strong>A GPU already assigned</strong> — either in a VM via VFIO or attached to at least one LXC. If you haven't assigned it yet, start from Add GPU to VM / LXC instead.",
"iommu":"<strong>IOMMU must be active on the host</strong> when switching <em>to</em> VM mode. Firmware settings and kernel support both matter. If <code>intel_iommu=on</code> or <code>amd_iommu=on</code> is missing from the running kernel, the script adds it with <code>iommu=pt</code> to <code>/etc/kernel/cmdline</code> (ZFS-root marker) or <code>/etc/default/grub</code>, then runs <code>proxmox-boot-tool refresh</code> or <code>update-grub</code>. Check any warnings and reboot when prompted.",
"reboot":"<strong>Plan for a reboot.</strong> Persistent driver and boot changes may require rebuilding initramfs and rebooting. The script presents a reboot prompt at the end.",
"knowList":"<strong>Know which VMs / LXCs are using the GPU.</strong> The script will find them and ask what to do with each, but it's faster if you already know the list."
"body":"The script blocks VM mode for device IDs <code>8086:5a84</code> and <code>8086:5a85</code> under its compatibility policy. If a selected GPU matches, it stops the VM-mode switch and returns to GPU selection, or exits when it is the only GPU. This blocklist does not prevent switching <em>to</em> LXC mode; other checks can still apply."
"body":"GPU selection and direction are reviewed before the main switch. A separate stale-VFIO cleanup can ask for confirmation earlier, and affected guests have their own conflict prompts. Read each confirmation: there is not one final confirmation covering every possible change."
"body":"The script scans every VGA / 3D / Display controller on the host and inspects <code>/sys/bus/pci/devices/*/driver</code> to find the current kernel driver. You'll see each GPU labelled with its name, PCI slot and current driver binding — so you can tell at a glance which mode it's in.",
"imageAlt":"GPU checklist showing each detected GPU with its current driver (vfio-pci / nvidia / amdgpu / i915) and PCI slot"
},
"pickGpu":{
"title":"Pick the GPU(s) to switch",
"body":"Single GPU → auto-selected. Multiple GPUs → checklist. You can tick several, but they must all be in the <em>same</em> current mode — otherwise the script can't pick a target mode for the batch and you get a \"mixed mode\" warning asking you to narrow the selection.",
"tipTitle":"Batching switches",
"tipBody":"Useful when you're rebuilding a host: \"All three NVIDIAs go to VM mode, then the iGPU goes back to LXC.\" Two runs, each with uniform target, much less friction than one-at-a-time."
},
"direction":{
"title":"Review the proposed direction",
"intro":"Based on the current mode, the script proposes the opposite as target:",
"items":[
"<strong>VM → LXC:</strong> unbind from <code>vfio-pci</code>, let the native driver (<code>nvidia</code>, <code>amdgpu</code>, <code>i915</code>) reclaim the card so LXCs can share it. On NVIDIA, the per-BDF entry is removed from <code>/etc/udev/rules.d/10-proxmenux-vfio-bind.rules</code> so the nvidia module reclaims the GPU after reboot.",
"<strong>LXC → VM:</strong> prepares <code>vfio-pci</code> ownership. AMD / Intel use native-driver blacklisting and <code>options vfio-pci ids=…</code>. For NVIDIA, <code>nvidia</code> is globally blacklisted only when every host NVIDIA GPU is in VFIO; otherwise per-BDF rules set <code>driver_override=vfio-pci</code> for the affected IOMMU-group devices, and NVIDIA GPUs outside those groups keep <code>nvidia</code>. Review every group member before switching."
"body":"The script checks <code>/etc/pve/lxc/*.conf</code> for GPU-device references by driver family, and <code>/etc/pve/qemu-server/*.conf</code> for PCI assignments. LXC detection is not a precise per-card BDF match. Review the detected guests and choose how to handle each:",
"removeWhen":"Choose this if the guest should operate without the GPU. Check its application settings first: CPU fallback is application-dependent, and removing the device does not automatically reconfigure the app.",
"body1":"Many dedicated NVIDIA / AMD GPUs expose HDMI audio at function <code>.1</code> of the same slot; additional audio devices may also have been assigned. Removing the GPU can leave obsolete <code>hostpci</code> audio entries in the VM. Review which devices should remain assigned.",
"body2":"The script discovers them (precise BDF match, no substring false-positives) and shows a checklist so you can remove them cleanly. It also cleans their vendor:device IDs from <code>/etc/modprobe.d/vfio.conf</code> — but only if no other VM still uses those audio IDs."
"body":"Once you confirm, the script writes the host-side changes — <code>vfio.conf</code>, blacklist, modules, and (for NVIDIA) the per-BDF udev rule at <code>/etc/udev/rules.d/10-proxmenux-vfio-bind.rules</code> plus the BDF state at <code>/etc/proxmenux/vfio-bind.bdfs</code>. It also applies the chosen conflict policy to each affected VM/LXC. If the host config actually changed, it runs <code>update-initramfs -u -k all</code> followed by <code>proxmox-boot-tool refresh</code>; otherwise both are skipped."
"body":"The new GPU binding only takes effect after a reboot. The script prompts you; you can reboot now or later, but don't start the target VM/LXC until the host has rebooted — otherwise the GPU is still held by the previous driver.",
"imageAlt":"Summary dialog listing what changed, followed by the reboot prompt"
"intro":"Before a <strong>VM → LXC</strong> switch, inspect the driver and existing per-BDF policy. This NVIDIA example uses vendor:device <code>10de:2204</code>; adapt it to your card. These commands inspect state; the script also manages affected guests and IOMMU-group members.",
"lxcToVm":"Before <strong>LXC → VM</strong>, inspect the selected PCI address and its IOMMU group. Replace the example address with yours and review all group members before assigning devices.",
"oneVmTitle":"Only one VM can use a given vfio-pci GPU at a time",
"oneVmBody":"Putting multiple <code>hostpci</code> entries with the same PCI slot in two VMs is valid config but only one of the VMs can start with the GPU — the second one will fail. The ProxMenux conflict policy step is exactly about avoiding this trap."
},
"verification":{
"heading":"Verification after reboot"
},
"troubleshoot":{
"heading":"Troubleshooting",
"stillVfioTitle":"GPU still shows vfio-pci after switching to LXC mode",
"stillVfioBody":"A loaded VFIO module does not prove which driver owns this GPU. Check the card binding and whether <code>update-initramfs</code> and the reboot completed. <code>lsmod | grep vfio</code> only lists modules. For AMD / Intel inspect <code>vfio.conf</code>; for NVIDIA inspect <code>/etc/proxmenux/vfio-bind.bdfs</code> and <code>/etc/udev/rules.d/10-proxmenux-vfio-bind.rules</code>. Correct stale policy before running <code>update-initramfs -u -k all</code> and rebooting.",
"vmFailBody":"Check whether the VM still has obsolete <code>hostpci</code> references. The <em>Remove GPU from config</em> policy can remove them during the intended switch; inspect the proposed direction before rerunning the script so you do not reverse the mode unintentionally. Alternatively, remove the obsolete assignment in Proxmox with the VM stopped.",
"smiFailBody":"Compare the loaded host NVIDIA module with the installed userspace libraries, including those in LXCs. Align versions first; a reboot loads the installed module but cannot repair mismatched library packages. Reloading with <code>modprobe -r nvidia</code> and <code>modprobe nvidia</code> requires stopped GPU clients and may fail while dependent modules are in use.",
