If Proxmox says QEMU guest agent is not running, reinstalling the agent is often not the fix.

First check that the agent is enabled in Proxmox, confirm the service is running inside the VM, and verify the virtio-serial channel. If the option was enabled while the VM was running and the channel is absent, a full stop and start from Proxmox is a sensible next step; reinstalling the guest package cannot create a missing host-side virtual device.

If Linux reports A dependency job for qemu-guest-agent.service failed, check whether /dev/virtio-ports/org.qemu.guest_agent.0 exists. When that device is missing, first verify the Proxmox VM option and restart the VM from a fully stopped state.

Which message do you see?

  • Guest agent not running: On the Proxmox host, first check whether QEMU Guest Agent is enabled for the VM. Start with the quick fix .
  • No guest agent configured: On the Proxmox host, first check VM → Options → QEMU Guest Agent is enabled and the change has taken effect. If you enabled it while the VM was running, fully stop and start the VM. See the VM option check and configured-agent checks .
  • A dependency job for qemu-guest-agent.service failed: Inside the Linux VM, first check whether /dev/virtio-ports/org.qemu.guest_agent.0 exists. Follow the dependency-failure checks .

Quick fix

From the Proxmox host:

qm config <vmid> | grep -E 'agent|serial'
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. Fully stop the VM in Proxmox.
  2. Start it again.
  3. Wait 30–60 seconds.
  4. 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

Now fully stop and start the VM.

Do not just reboot from inside the guest OS.

The virtio-serial channel used by the agent is created when the VM powers on. If you enable QEMU Guest Agent while the VM is already running, a normal guest reboot may leave you with the same error.

“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:

What you findMost likely causeWhat to do
The channel is missingQEMU Guest Agent is disabled in Proxmox, or the VM has not cold-started since it was enabledEnable it, fully stop the VM, then start it again
The channel exists but the service failedThe device is available, but the service needs another start or has a separate errorReset the failed state, restart it and read the journal
qm agent <vmid> ping worksHost-to-guest communication is workingWait 30–60 seconds and refresh the Proxmox UI

If the channel is missing, run this on the Proxmox host:

qm set <vmid> --agent enabled=1

Then fully stop the VM, start it from Proxmox and check again inside the guest:

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

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.

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 is masked or failed:

systemctl unmask qemu-guest-agent
systemctl reset-failed qemu-guest-agent
systemctl restart qemu-guest-agent
journalctl -u qemu-guest-agent -b --no-pager

Then return to the Proxmox host:

qm set <vmid> --agent enabled=1

Fully stop the VM, start it again, and test:

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 VirtIO ISO version that matches the rest of the VirtIO drivers installed in the VM.

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

This is especially common if QEMU Guest Agent was enabled in Proxmox after Windows and the VirtIO drivers were already installed.

Try:

  1. Disable QEMU Guest Agent in the VM options.
  2. Fully stop the Windows VM.
  3. Enable QEMU Guest Agent again.
  4. Start the VM.
  5. Wait 30–60 seconds.
  6. Test:
qm agent <vmid> ping

This forces Proxmox to recreate the device.

Check the virtio-serial device

Even with the guest agent installed and running, communication can fail if the host/guest channel is missing.

From the Proxmox host:

qm config <vmid> | grep serial

Enabling QEMU Guest Agent is supposed to configure the required channel automatically.

If the agent is enabled and running but Proxmox still cannot reach it:

  1. Go to VM → Options → QEMU Guest Agent.
  2. Disable it.
  3. Fully stop the VM.
  4. Enable QEMU Guest Agent again.
  5. Start the VM.
  6. Run:
qm agent <vmid> ping

Do not soft-reboot between those steps.

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
  1. Verify the service:
Get-Service QEMU-GA
  1. Make sure QEMU Guest Agent is enabled in Proxmox.
  2. Fully stop and start the VM once.
  3. Test from the host:
qm agent <vmid> ping

Avoid standalone MSI files from random mirrors. Keeping the guest agent and the rest of the VirtIO stack on matching versions removes another possible source of problems.

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 whether the guest-agent channel exists:

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

If it is missing, enable QEMU Guest Agent for the VM in Proxmox, fully stop the VM and start it again. If it exists, reset and restart the service, then inspect its boot journal:

systemctl reset-failed qemu-guest-agent
systemctl restart qemu-guest-agent
journalctl -b -u qemu-guest-agent --no-pager

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.