How to install the QEMU guest agent on Ubuntu and Debian (Proxmox VE 9)

To install the QEMU guest agent on Ubuntu or Debian, run sudo apt install qemu-guest-agent inside the VM, turn on QEMU Guest Agent in the VM's Options in Proxmox, then shut the VM down and start it again from Proxmox. A reboot from inside the guest isn't enough.

That's it for most people. The rest of this guide covers why systemctl enable prints a scary warning (you can ignore it), how to test the agent from the Proxmox host, and what to check when Proxmox still says "QEMU guest agent is not running".

This works the same on Ubuntu 22.04, 24.04 and 26.04, Debian 12 and 13, and on Proxmox VE 8 and 9.

What the guest agent does

The guest agent is a small service inside the VM that talks to Proxmox over a virtio serial channel. With it, Proxmox can:

• show the VM's IP addresses on the Summary page
• shut down the VM cleanly instead of relying on ACPI
• freeze the filesystem during backups and snapshots, so you get consistent images
• run fstrim after cloning or migration to give space back to thin storage
• set the guest clock after a restore or resume

Without it, Proxmox works, but backups of busy VMs are only crash-consistent and you have to look up IPs yourself.

Step 1: enable the agent in Proxmox

In the Proxmox web UI, select the VM, open Options, double-click QEMU Guest Agent and tick Use QEMU Guest Agent.

Or from the Proxmox host shell, as the Proxmox wiki shows (replace 100 with your VM ID):

qm set 100 --agent enabled=1

I'd also turn on fstrim_cloned_disks if your storage is thin-provisioned (LVM-thin, ZFS, Ceph):

qm set 100 --agent enabled=1,fstrim_cloned_disks=1

This adds a virtio serial device to the VM. New hardware only appears after a full power cycle, which is step 3.

Step 2: install qemu-guest-agent in Ubuntu or Debian

SSH into the VM (or use the Proxmox console) and run:

sudo apt update
sudo apt install -y qemu-guest-agent

Same package name on Ubuntu and Debian. On a minimal Debian install without sudo, run it as root.

Step 3: shut down and start the VM from Proxmox

qm shutdown 100 && qm start 100

Or click Shutdown, wait until the VM is stopped, then click Start. Don't use Reboot here: a reboot keeps the same QEMU process, so the new serial device doesn't show up.

After boot, systemd starts the agent automatically when it sees the device. No enable needed.

About the systemctl enable warning

Most older guides, including the first version of this one, tell you to run systemctl enable qemu-guest-agent. On Ubuntu and Debian that prints:

The unit files have no installation config (WantedBy=, RequiredBy=, Also=,
Alias= settings in the [Install] section, ...).
This means they are not meant to be enabled using systemctl.

That's expected. The unit is static: a udev rule starts it when the virtio port org.qemu.guest_agent.0 appears. An Ubuntu developer explained this in Launchpad bug 1883009. So skip enable. If you don't want to wait for the power cycle and the device is already there, you can start it by hand:

sudo systemctl start qemu-guest-agent

Check that it works

Inside the VM, check the service and the device:

systemctl status qemu-guest-agent
ls -l /dev/virtio-ports/

You want Active: active (running) and an entry called org.qemu.guest_agent.0.

On the Proxmox host, ping the agent. No output means it answered:

qm agent 100 ping

A few more useful commands:

qm agent 100 network-get-interfaces   # IPs the guest reports
qm agent 100 get-osinfo               # distro and kernel
qm agent 100 get-fsinfo               # mounted filesystems

In the web UI, the VM's Summary page now shows its IP addresses.

If you clone VMs from a template and they all get the same IP, that's a different problem (machine-id), covered in Proxmox cloned VM has the same IP.

"QEMU guest agent is not running": fixes

Work through these in order:

1. Option not enabled. On the host, qm config 100 | grep agent should show agent: enabled=1 (or agent: 1). If not, go back to step 1.
2. VM was only rebooted. Do a full shutdown and start from Proxmox.
3. Device missing in the guest. If /dev/virtio-ports/org.qemu.guest_agent.0 doesn't exist, the VM still hasn't been power-cycled since you enabled the option.
4. Service not running. sudo systemctl start qemu-guest-agent, then check journalctl -u qemu-guest-agent -b for errors.
5. Package not installed. Check with dpkg -l qemu-guest-agent. Minimal and cloud images often don't include it.
6. Shutdown hangs from Proxmox. If the agent is enabled in Proxmox but not installed in the guest, Proxmox can wait for an agent that never answers. Install the agent, or turn the option off for that VM.

Install it automatically with cloud-init

If you build VMs from a cloud image template, add the agent to your cloud-init user data so every new VM has it from the first boot:

#cloud-config
packages:
  - qemu-guest-agent
runcmd:
  - systemctl start qemu-guest-agent

If you create VMs with Terraform, the same user data plugs into the setup from my Terraform and Proxmox tutorial. Remember the VM option still needs agent: 1 in the template.

Do LXC containers need it?

No. Containers share the host kernel, so Proxmox already sees their IPs and can stop them cleanly. The guest agent is only for full virtual machines.

My take

Install the agent in every Linux VM on Proxmox. It costs a few megabytes of RAM and you get clean shutdowns, consistent backups and IPs on the Summary page. Bake it into your templates once and you stop thinking about it.

FAQ

How do I install the QEMU guest agent on Ubuntu 24.04?

Run sudo apt update && sudo apt install -y qemu-guest-agent, enable QEMU Guest Agent in the VM's Options in Proxmox, then shut the VM down and start it again. The same steps work on Ubuntu 22.04 and 26.04.

How do I install the Proxmox guest agent on Debian?

The package is the same: apt install qemu-guest-agent as root or with sudo. Debian 12 and 13 both have it in the main repository. Enable the option in Proxmox and power-cycle the VM.

Do I need to run systemctl enable qemu-guest-agent?

No. The service is static and starts automatically through a udev rule when the virtio serial device is present. The warning from systemctl enable is harmless.

Why does Proxmox say "QEMU guest agent is not running"?

Usually the agent option was enabled but the VM was only rebooted, not shut down and started. Power-cycle it from Proxmox and check that /dev/virtio-ports/org.qemu.guest_agent.0 exists inside the guest.

Does the guest agent improve backups?

Yes. With the agent, Proxmox freezes the guest filesystems before a backup or snapshot and thaws them afterwards, so the backup is consistent instead of "as if the power was cut".