Proxmox Guest Agent Not Running: QEMU Fixes

If Proxmox shows QEMU guest agent is not running, check the VM option on the Proxmox node and the agent service inside the guest. Run qm agent <vmid> ping on the node to verify that the two can communicate.

Which message do you see?

Quick fix

From the Proxmox host:

qm config <vmid> | grep '^agent:'
qm agent <vmid> ping

You want to see the guest agent enabled:

agent: 1

or:

agent: enabled=1

If it is not enabled:

qm set <vmid> --agent enabled=1

Then:

1. If you just enabled the option while the VM was running, shut the guest down cleanly, confirm the VM is stopped in Proxmox, and start it again.
2. Once the guest has booted and the service has started, run:

qm agent <vmid> ping

A working agent normally returns without an error.

If you still get:

QEMU guest agent is not running

continue through the checks below.

Why Proxmox says “QEMU guest agent is not running”

The message does not necessarily mean the qemu-guest-agent package is missing.

Proxmox needs several things to work at the same time:

• QEMU Guest Agent enabled in the VM configuration
• the guest agent installed inside Linux or Windows
• the guest agent service running
• a working virtio-serial channel between host and guest

That last one causes a lot of confusion.

The service inside the VM can show as Running, while Proxmox still cannot communicate with it.

Make sure QEMU Guest Agent is enabled in Proxmox

Check the VM configuration:

qm config <vmid> | grep agent

If you do not see agent: 1 or agent: enabled=1:

qm set <vmid> --agent enabled=1

You can also enable it in the UI:

VM → Options → QEMU Guest Agent → Enabled

If you changed the agent option while the VM was running, shut the guest down cleanly and start it again from Proxmox. A fresh VM start applies the agent device configuration.

“No guest agent configured” / “Requires guest agent installed”

If Proxmox or another management tool reports no guest agent configured, start by checking whether Proxmox itself can reach QEMU Guest Agent:

qm agent <vmid> ping

If that fails, fix the Proxmox-to-guest communication first.

There is not a separate generic “Proxmox guest agent” you need to install on top of QEMU Guest Agent.

For Linux, the package is normally:

qemu-guest-agent

For Windows, QEMU Guest Agent is available through the VirtIO driver ISO.

Fix “A dependency job for qemu-guest-agent.service failed”

On Ubuntu, Debian and some other Linux guests, the complete error can look like this:

A dependency job for qemu-guest-agent.service failed.
See 'journalctl -xe' for details.

The service depends on the QEMU guest-agent virtio-serial device. Check for it inside the VM:

systemctl status qemu-guest-agent --no-pager
ls -l /dev/virtio-ports/
journalctl -b -u qemu-guest-agent --no-pager

The expected channel is:

/dev/virtio-ports/org.qemu.guest_agent.0

Use the result to choose the next step:

If the channel is missing, verify the VM option and apply a pending change with a clean shutdown and fresh start. After boot, check the exact device path inside the guest:

ls -l /dev/virtio-ports/org.qemu.guest_agent.0

If the path exists and the unit still fails, read the boot journal and inspect the installed unit with systemctl cat qemu-guest-agent before changing service settings.

Finally, test from the Proxmox host:

qm agent <vmid> ping

Do not create /dev/virtio-ports/org.qemu.guest_agent.0 manually. QEMU exposes that virtual device when the VM configuration and startup state are correct. This device-backed service behavior is documented in the QEMU guest-agent systemd unit and the QEMU Guest Agent documentation .

Proxmox documents the host-side option and supported uses in its QEMU Guest Agent guide . Package names, unit behavior, and Windows driver paths can change, so confirm the current guest OS and VirtIO documentation before installation.

Error opening channel: No such file or directory

If the journal names /dev/vtcon/org.qemu.guest_agent.0, compare that path with the device exposed in the guest. The upstream QEMU default for virtio-serial is /dev/virtio-ports/org.qemu.guest_agent.0.

• If the default device is also missing, start with the Proxmox VM option .
• If the default device exists but the error names another path, inspect systemctl cat qemu-guest-agent and the guest’s agent configuration for a path override. Confirm the expected path for your installed package before editing it.

Proxmox Guest Agent not running on Ubuntu / Debian

Inside an Ubuntu or Debian VM:

systemctl status qemu-guest-agent

If it is not installed:

apt update
apt install -y qemu-guest-agent

Check it again:

systemctl status qemu-guest-agent --no-pager

On many Debian and Ubuntu releases, this is a static, device-activated service. If systemctl enable qemu-guest-agent says the unit has no installation configuration, that message alone does not mean the package is broken. Make sure the channel exists, then restart the service:

ls -l /dev/virtio-ports/org.qemu.guest_agent.0
systemctl restart qemu-guest-agent

If the service fails with the device present, check the boot journal for the specific error. If systemd reports a masked unit, check why it was masked before changing the service state.

journalctl -b -u qemu-guest-agent --no-pager

Once the guest service is active, verify it from the node with qm agent <vmid> ping.

Ubuntu-specific trap

A common sequence is:

1. Install qemu-guest-agent in Ubuntu.
2. Enable QEMU Guest Agent in Proxmox.
3. Reboot Ubuntu.
4. Proxmox still says the guest agent is not running.

The package may be completely fine.

Fully stop and start the VM from Proxmox instead of rebooting it from Ubuntu.

Proxmox Guest Agent not running on RHEL / Rocky / AlmaLinux

Install and enable the service:

dnf install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

Then verify:

systemctl status qemu-guest-agent

If you see a dependency failure, check the virtio-serial channel and make sure the agent is enabled in the Proxmox VM configuration.

Proxmox Guest Agent not running on Windows

For Windows guests, install QEMU Guest Agent from the VirtIO driver ISO.

The installer is normally:

guest-agent\qemu-ga-x86_64.msi

Use the signed VirtIO ISO for your Windows version and architecture.

After installation, open PowerShell:

Get-Service QEMU-GA

The service should be Running and configured to start automatically.

If it is stopped:

Start-Service QEMU-GA
Set-Service QEMU-GA -StartupType Automatic

Then test from the Proxmox host:

qm agent <vmid> ping
qm agent <vmid> network-get-interfaces

If Get-Service QEMU-GA says Running but qm agent <vmid> ping still fails, reinstalling the MSI is probably not the next thing to try.

The problem is likely the communication channel between Proxmox and the VM.

Windows Guest Agent installed but still not running

If Windows reports QEMU-GA as running but the node cannot ping it, verify that the agent option is enabled and that the VM has had a fresh start since the option changed. In Windows Device Manager, check for a missing or errored VirtIO Serial device. If the driver is missing, use the signed driver from the Proxmox VirtIO driver guide for your Windows version and architecture.

Check the virtio-serial device

For Linux guests using the default transport, check the device path and service logs . On Windows, verify the VirtIO Serial driver and the QEMU-GA service. From the Proxmox node, qm agent <vmid> ping verifies communication end to end.

Give Proxmox a minute

Proxmox does not update every guest-agent field in the UI instantly.

After starting the VM, wait roughly 30–60 seconds before deciding that it is still broken.

If:

qm agent <vmid> ping

works but the Summary page still does not show the guest IP, refresh the UI after a minute.

If qm agent works, communication between the host and guest agent is working.

Install qemu-ga-x86_64.msi on Windows

For a Windows VM:

1. Get the current stable VirtIO driver ISO.
2. Attach the ISO as a CD/DVD drive to the VM.
3. Open the ISO inside Windows.
4. Run:

guest-agent\qemu-ga-x86_64.msi

5. Verify the service:

Get-Service QEMU-GA

6. Make sure QEMU Guest Agent is enabled in Proxmox.
7. Fully stop and start the VM once.
8. Test from the host:

qm agent <vmid> ping

Use the VirtIO ISO linked by Proxmox as the installer source.

Why QEMU Guest Agent matters

A missing guest agent is not always critical.

Your VM can run normally without it.

But QEMU Guest Agent gives Proxmox additional communication with the guest, including information and operations used for VM management.

Two places where you may notice the difference are shutdowns and backups.

Clean shutdowns

Without working guest communication, scheduled shutdown or reboot operations can fail or take longer than expected.

Backup consistency

With a working guest agent, Proxmox can coordinate filesystem freeze/thaw operations during supported snapshot workflows.

Without it, a VM backup can still run, but it may only represent the filesystem as it existed at the instant of the snapshot rather than after guest-assisted quiescing.

If the only symptom is a missing IP address on the Summary page, fixing the agent may not be urgent.

If backups or scheduled VM operations are affected, it is worth fixing.

FAQ

Why does Proxmox say “QEMU guest agent is not running” when it is installed?

Because installing the package is only one part of the setup.

Proxmox must also have QEMU Guest Agent enabled for that VM and be able to communicate with the service through the guest channel.

Check:

qm config <vmid> | grep agent
qm agent <vmid> ping

How do I fix “A dependency job for qemu-guest-agent.service failed”?

Check the virtio-serial channel and boot journal inside the VM. If the channel is missing after you enable the option, apply the change with a clean shutdown and fresh start. If the channel exists, use the journal to identify the service error.

I reinstalled qemu-guest-agent and it still says not running. What now?

Check the VM configuration and virtio-serial communication before reinstalling it again.

If the service is running, make sure the agent is enabled in Proxmox and fully stop/start the VM.

Does a normal reboot fix QEMU Guest Agent?

Not always.

If you just enabled QEMU Guest Agent in the Proxmox configuration, fully stopping and starting the VM is safer because the required virtual device is created at power-on.

How do I fix Proxmox Guest Agent on Ubuntu?

Install it:

apt install -y qemu-guest-agent

Then enable QEMU Guest Agent in Proxmox and fully stop/start the VM. Inside the guest, verify the service:

systemctl restart qemu-guest-agent
systemctl status qemu-guest-agent --no-pager

From the Proxmox host, test the connection:

qm agent <vmid> ping

How do I fix Proxmox Guest Agent on Windows?

Install:

guest-agent\qemu-ga-x86_64.msi

from the VirtIO ISO.

Check:

Get-Service QEMU-GA

Then enable QEMU Guest Agent in Proxmox and fully stop/start the VM.

qm agent <vmid> ping works but the Proxmox UI still says the agent is not running

Wait 30–60 seconds and refresh the page.

If qm agent <vmid> ping succeeds, the host can communicate with the guest agent.

Is it safe to ignore “Guest Agent Not Running”?

Usually, yes, if the VM itself is otherwise healthy and you do not need guest-assisted operations.

But it is worth fixing if you rely on Proxmox for automated shutdowns, guest information or filesystem-consistent snapshots.

Also seeing the subscription warning on a fresh node? Read Proxmox no valid subscription . Setting up a Windows lab VM next to this? Guest agent is also why Minecraft on Proxmox mentions it in the pitfalls list.