GPU-PV Automation Scripts

Scripts to automate GPU passthrough (GPU-PV) setup on Linux VMs in Hyper-V.

Important stuff to know

SUPER IMPORTANT: These scripts are written with CLANKER SLOP's assistance. They may contain bugs, security issues, or just plain bad practices. Use at your own risk. Review the code before running it. Test in a safe environment first.

Tested configuration:

• Windows 11 host with Hyper-V
• Debian 13 (Trixie) guest
• NVIDIA GPU

What this enables:

• CUDA compute (PyTorch, TensorFlow, etc)
• NVENC/NVDEC hardware encoding
• GPU compute workloads

What this does NOT do:

• Graphics/desktop acceleration (no OpenGL/Vulkan)
• Gaming in the VM
• Display output acceleration

Other distros (Arch, Ubuntu, RHEL, etc) might work but are untested. AMD/Intel GPUs have detection logic but haven't been tested. Your mileage may vary. I would appreciate if you test on your setup and open PRs/issues with results.

What's in here

Windows host scripts (PowerShell):

• Setup-GPUPV-Host.ps1 - Initial VM and GPU configuration
• Update-GPUPV-Drivers-Host.ps1 - Update drivers after Windows GPU driver updates
• Schedule-GPUPV-DriverCheck.ps1 - Schedule automatic update checks

Linux guest scripts (Bash):

• setup-gpupv-guest.sh - Build kernel module, install drivers, configure system
• update-gpupv-drivers-guest.sh - Replace drivers and rebuild module

Quick start

Initial setup

On Windows (as admin):

.\Setup-GPUPV-Host.ps1

Pick your VM and GPU, script handles the rest.

On Linux (as root) if you choose to manually run the guest setup script:

sudo ./setup-gpupv-guest.sh

Installs everything and builds the dxgkrnl kernel module. Takes a while.

Reboot when done.

Verify it worked

lsmod | grep dxgkrnl        # module loaded?
nvidia-smi                  # GPU visible?

Updating drivers later

After updating GPU drivers on Windows:

# On Windows
.\Update-GPUPV-Drivers-Host.ps1

# On Linux
sudo ./update-gpupv-drivers-guest.sh
sudo reboot

How it works

1. Host script configures VM with GPU partition adapter
2. Stages Windows GPU drivers and WSL libraries
3. Transfers to Linux guest
4. Guest script builds dxgkrnl module from WSL2 kernel source
5. DKMS manages module rebuilds on kernel updates
6. Drivers get installed to /usr/lib/wsl/drivers/

DKMS should automatically rebuild the module when you update your kernel. Usually.

Requirements

Windows:

• Windows 11 or Server 2022+
• Hyper-V with GPU-PV support (Get-VMHostPartitionableGpu to check)
• PowerShell 5.1+
• OpenSSH client (optional, for remote transfer)
• Not a potato

Linux:

• Kernel headers for your running kernel
• Build tools (gcc, make, etc)
• DKMS
• Git
• Assign resources (CPU, RAM) to VM appropriately

Documentation

• AUTOMATED-SETUP-GUIDE.md - Detailed setup walkthrough
• UPDATE-GUIDE.md - How to update drivers

Common problems

"No partitionable GPUs found"
Your GPU doesn't support GPU-PV. Check with Get-VMHostPartitionableGpu.

DKMS build fails
Check /var/lib/dkms/dxgkrnl/<version>/build/make.log. Usually missing kernel headers or wrong kernel version (Arch users: use LTS kernel if you're on >6.12).

Module loads but no GPU
Check VM config: Get-VMGpuPartitionAdapter -VMName YourVM
Check /dev/dri/ exists.

nvidia-smi not found
Script installs driver libraries, not the full CUDA toolkit. Install that separately if you need it.

Performance

Expect around 90-95% of bare metal for CUDA. NVENC is pretty close to native. This isn't as fast as proper PCIe passthrough but has the advantage of being able to share the GPU between multiple VMs.

Kernel updates

DKMS handles this automatically - just reboot after updating your kernel. If it doesn't work:

sudo dkms build -m dxgkrnl -v <version> -k $(uname -r)
sudo dkms install -m dxgkrnl -v <version> -k $(uname -r)
sudo reboot

GPU driver updates

When Windows updates your GPU drivers, run the update scripts on both host and guest, then reboot the guest. The guest script backs up the old drivers automatically (keeps last 3).

Security notes

• Scripts use -o StrictHostKeyChecking=no for SSH to make life easier
• Needs admin on Windows, root on Linux
• No driver signature verification
• Use SSH keys instead of passwords if you're paranoid

Contributing

This is mostly a personal thing but feel free to open issues or submit PRs if you get it working on other distros/GPUs.

Credits

Based on various GPU-PV community guides and Microsoft's WSL2 kernel source.

Special thanks to Nislaco for the original scripts and ideas. I got GPU-PV working on Debian by following their guides.