Unraid - VMs

🛠 How to Fix “Requires Guest Agent Installed” on Unraid for Ubuntu VMs

October 16, 2025 - By quentinmayo

If you’re running an Ubuntu virtual machine (VM) on Unraid and see the message:

“Requires guest agent installed”

…you’re not alone. This means the QEMU Guest Agent isn’t installed or isn’t being detected by Unraid.
Fortunately, it’s an easy fix.

In this guide, I’ll show you how to install and configure the QEMU Guest Agent so Unraid can properly communicate with your Ubuntu VM.

🔍 What is the QEMU Guest Agent?

The QEMU Guest Agent is a background service that runs inside your virtual machine. It allows Unraid (and any hypervisor using QEMU/KVM) to gather detailed information from the guest system.

Key features include:

✅ Accurate IP address reporting
✅ Shutdown/reboot control from the Unraid UI
✅ Disk usage statistics
✅ Time synchronization
✅ Live migration support (for advanced setups)

If it’s missing, Unraid will display the warning:

“Requires guest agent installed.”

✅ How to Install the QEMU Guest Agent on Ubuntu

Follow these steps to get the guest agent installed and running.

1. Open your Ubuntu VM terminal

You can access it via the Unraid VM console or SSH into your Ubuntu VM.

2. Update your package list

sudo apt update

3. Install the guest agent

sudo apt install qemu-guest-agent -y

4. Enable and start the service

sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent

Verify that it’s running:

sudo systemctl status qemu-guest-agent

You should see the service listed as active (running).

🔁 Reboot Your VM (Optional)

In most cases, no reboot is required.
However, if Unraid still doesn’t detect the agent, try restarting your VM:

sudo reboot

Or use the Unraid web UI to power cycle the VM.

✅ Final Result: No More Warning!

After completing these steps:

The “Requires guest agent installed” message should disappear
Unraid will display the VM’s IP address and other guest info
Shutdown and restart functions will work more smoothly

💡 Bonus Tip: Check VM Settings in Unraid

1.	Go to VMs > Edit your Ubuntu VM
2.	Scroll down to "QEMU Guest Agent"
3.	Make sure it’s set to Yes

🧩 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 easy to fix — just install and enable the qemu-guest-agent package in Ubuntu.
Once it’s running, Unraid gains better visibility and control over your VM — including IP reporting, graceful shutdowns, and smoother management.

Would you like me to make a styled HTML version (with inline CSS and icons) so it looks great even without shortcodes/plugins? That version would work perfectly in any WordPress theme or static page builder.