🛠 How to Fix “Requires Guest Agent Installed” on Unraid for Ubuntu VMs
If you're running an Ubuntu virtual machine (VM) on Unraid and you see the message:
“Requires guest agent installed”
...you're not alone. This message means the QEMU Guest Agent isn’t installed or isn’t being detected by Unraid. Fortunately, it's easy to fix.
In this quick guide, I’ll walk you through exactly how to get the QEMU Guest Agent installed and properly running so that Unraid can communicate more effectively with your Ubuntu VM.
🔍 What is the QEMU Guest Agent?
The QEMU Guest Agent is a background service that runs inside your VM and allows Unraid (or any hypervisor using QEMU/KVM) to gather more detailed info from the guest system.
This enables features like:
Reporting accurate IP addresses
Shutdown/reboot from the Unraid UI
Disk usage stats
Time synchronization
Live migration support (for advanced setups)
If it's missing, Unraid will show the warning: "Requires guest agent installed."
✅ Steps to Install QEMU Guest Agent on Ubuntu
Here’s how to fix the issue:
1. Open your Ubuntu VM terminal
You can do this directly in the Unraid VM console or by SSH-ing into your Ubuntu VM.
2. Update your package list
bash
CopyEdit
sudo apt update
3. Install the guest agent
bash
CopyEdit
sudo apt install qemu-guest-agent -y
4. Enable and start the service
bash
CopyEdit
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent
You can verify it's running with:
bash
CopyEdit
sudo systemctl status qemu-guest-agent
You should see output indicating the service is active (running).
🔁 Reboot Your VM (Optional)
In most cases, no reboot is needed — but if Unraid still doesn’t detect the agent, try restarting your VM:
bash
CopyEdit
sudo reboot
Or use the Unraid UI to power cycle the VM.
✅ Final Result: No More Warning!
After these steps:
The warning should disappear from the VM's status page in Unraid
You’ll start seeing guest info like IP addresses
Shutdown/restart options will function more smoothly
💡 Bonus Tip: Check VM Settings in Unraid
Make sure the "QEMU Guest Agent" option is enabled for the VM in Unraid:
Go to VMs > Edit your Ubuntu VM
Scroll down to "QEMU Guest Agent"
Make sure it’s set to Yes
If it’s off, even with the agent running in Ubuntu, Unraid won't use it.
🧩 Troubleshooting
If you still don’t see it working:
Double-check that qemu-guest-agent is running (systemctl status)
Check the VM’s XML for the <channel> device — Unraid usually adds this automatically
Look in the Unraid syslog for guest agent connection errors
📌 Summary
The “Requires guest agent installed” warning is a simple fix — just install and enable the qemu-guest-agent in Ubuntu. Once it’s running, Unraid gains better visibility and control over your VM.