Proxmox QEMU Guest Agent: Install & Enable

The QEMU guest agent is a small service inside a VM that talks to Proxmox. With it, Proxmox shows the VM's IP addresses, shuts it down cleanly and freezes the filesystem during backups and snapshots so data stays consistent.

Before you start

A running Proxmox VM and console or SSH access to it.
For Windows: the VirtIO driver ISO, which includes the agent installer.

Enable the agent in Proxmox

Select the VM → Options → QEMU Guest Agent → Edit.
Tick Use QEMU Guest Agent and save.
Fully stop and start the VM (a reboot from inside is not enough) so the virtual serial channel is added.

Shell equivalent:

qm set 105 --agent enabled=1

Install the QEMU guest agent in Linux

Debian and Ubuntu:

apt install qemu-guest-agent -y

AlmaLinux, Rocky and other RHEL-family systems:

dnf install qemu-guest-agent -y

Then start it:

systemctl enable --now qemu-guest-agent

Install it in Windows

Attach the VirtIO ISO to the VM's CD drive.
Run guest-agent\qemu-ga-x86_64.msi from the ISO (or the full virtio-win-guest-tools installer).
Check that the QEMU Guest Agent service is running in Services.

Check it works

The VM's Summary shows its IP addresses.
From the host:

qm agent 105 ping

No output and no error means the agent answered.

Note: With the agent enabled, Proxmox uses it for Shutdown and for filesystem freeze during snapshot-mode backups. If the agent is enabled in Proxmox but not running in the guest, those actions can hang until they time out.

Troubleshooting

"QEMU guest agent is not running": the service is not installed or not started in the guest, or the VM was not power-cycled after enabling the option.
Backups stall at freeze: update the agent; as a workaround, disable freeze in the agent options for that VM.
No IPs shown on Windows: install the full guest tools package and restart the service.

Frequently asked questions

Is the guest agent required?

No, but it is strongly recommended for clean shutdowns and consistent backups.

Does it work in containers?

LXC containers do not need it; Proxmox manages them directly.

Is it a security risk?

It only talks over a local virtual channel to the host, which already controls the VM.

Next steps

Was this guide helpful?

Still stuck?

Ask MdmHost AI for a quick answer, or open a ticket and our team will take a look. We are here 24/7.

Ask MdmHost AI Open a ticket