How to Fix a Black Screen in a Proxmox VE VM (Display Types: std VGA, VirtIO-GPU, and SPICE Explained)

Introduction

You spin up a fresh VM in Proxmox VE, click Console, and… nothing. A blinking cursor, a black rectangle, or a screen that never gets past the boot logo. Nine times out of ten this has nothing to do with the VM being broken — it's the graphics adapter Proxmox handed it that doesn't match what the guest operating system expects.

Proxmox calls this setting Display in the GUI and vga in the config file, and it's one of those options people click past during VM creation without a second thought. Then months later they're staring at a black screen wondering what broke.

This one covers what the display types actually do, which one fits Linux, Windows, and headless server VMs, and how to fix a console that refuses to show anything.

What You Will Learn

• What the Proxmox VE display setting actually controls under the hood
• The difference between Standard VGA, VirtIO-GPU, SPICE (QXL), and VMware compatible
• How to change the display type from the GUI and from the shell
• Why changing it needs a full VM restart, not just a reboot inside the guest
• How to fix the black-screen and stuck-resolution problems people hit most often

What Is This Feature?

Every virtual machine needs some kind of graphics card so the guest operating system has something to draw its screen onto. Proxmox VE runs on QEMU and KVM under the hood, and QEMU can emulate several different types of virtual graphics hardware. You pick one per VM under Hardware → Display.

Run qm config <vmid> against any VM and, if you've ever changed this setting, you'll see a line like vga: std or vga: qxl. If there's no vga line at all, the VM is quietly using the built-in default. That one line decides three things: what resolutions are available, whether the guest can use hardware-accelerated graphics, and which console technology you use to actually view it — the browser-based noVNC console, or a dedicated SPICE client running on your own computer.

Get the wrong one for a given guest OS and you get exactly the symptoms above: a black screen during boot, a resolution frozen at 1024x768 with no way to resize the window, or a console that technically connects but feels sluggish and unresponsive.

The Display Types at a Glance

Why Would You Use It?

Most people never touch this setting on purpose. It becomes relevant the moment you hit one of these situations:

• You're installing Windows and the installer is stuck at a tiny fixed resolution you can't resize
• You want copy-paste and dynamic window resizing between your desktop and a Linux VM
• You're running a headless Linux server VM and don't need a virtual display taking up resources at all
• You're passing a physical GPU through to the VM, and Proxmox's virtual display is just getting in the way of the real one

Picking the right type up front saves you from redoing it later. And as you'll see in a moment, changing it after the fact means a full VM restart, not a click on Reboot inside the guest — which is the part that trips almost everyone up the first time.

Prerequisites

Before you start, you'll want:

• A working Proxmox VE 8.x or 9.x host — the vga options covered here have been stable across both
• At least one existing VM. The examples below use VMID 101; swap in your own
• Shell access to the Proxmox host, either through the web-based Shell under the node, or SSH
• Permission to stop and start the VM. This is a hardware-level change, so a brief outage is unavoidable

You don't need to install anything extra on the Proxmox host for this. The display types are built into QEMU, which ships with Proxmox VE by default.

Step-by-Step Tutorial

Check What Display Type You're Currently Using

Open the Proxmox web interface, click your VM in the left-hand tree, then go to Hardware. You'll see a row called Display with the current type listed, something like Default (std) or SPICE (qxl).

Prefer the command line? SSH into the host and run:

qm config 101

Look for the vga line in the output. No line means the VM is on the default, which is std.

Changing the Display Type From the GUI

In Hardware, double-click the Display row (or select it and click Edit). A dropdown opens with your options — typically Default, SPICE, VirtIO-GPU, VirtIO-GPU (GL), Standard VGA, VMware compatible, and none. Pick one and click OK.

Nothing changes visually yet. Proxmox has updated the config file, but the running VM is still using the old virtual hardware until it's restarted.

Changing the Display Type From the Shell

The equivalent command is:

qm set 101 --vga virtio

Swap virtio for whichever type you need: std, qxl, vmware, virtio-gl, or none. This is the faster route if you're scripting VM builds or managing a dozen VMs where clicking through the GUI one at a time gets old fast.

Restart the VM — Not Just Reboot the Guest

This is the step almost everyone skips at first. Display type is virtual hardware, and QEMU only builds a VM's hardware layout when its process starts. Rebooting the operating system inside the VM does not rebuild that hardware — you have to stop the VM completely and start it again:

qm stop 101
qm start 101

Or from the GUI: right-click the VM, choose Stop, wait for the status to go grey, then choose Start. A plain Reboot click will not apply a new display type.

Setting Up SPICE for a Better Console Experience

If you picked SPICE (the qxl type), the browser's noVNC console still opens fine, but you're leaving most of what SPICE actually offers on the table — dynamic resolution, clipboard sharing, audio, and a noticeably smoother feel than noVNC. To get the full experience:

• In the VM's console toolbar, change the console type dropdown from noVNC to SPICE
• Click Console — your browser downloads a small .vv file
• Open that file with a SPICE client on your own machine, such as virt-viewer or remote-viewer (both available on Windows and Linux)
• Inside the guest, install the SPICE guest tools on Windows, or the spice-vdagent package on Linux — without this, resolution still won't resize automatically even though the connection type is SPICE

Setting Up VirtIO-GPU for a Modern Linux Guest

VirtIO-GPU is the newer option and generally the best default for Linux desktop VMs on a recent kernel. Most current distributions — Ubuntu 22.04 and newer, Debian 12 and newer, Fedora — already ship the virtio-gpu kernel driver, so there's nothing extra to install inside the guest. Set the type, restart the VM, done.

VirtIO-GPU (GL) adds hardware-accelerated 3D through VirGL, worth it if you're running a full graphical desktop and want smoother window animations. It adds overhead on the Proxmox host, and support depends on the host's own GPU driver stack, so I wouldn't flip this on for a production VM without testing it on a spare one first.

Commands Explained

Common Errors

A handful of symptoms show up again and again in the Proxmox forums and homelab communities. Here's what's usually behind each one.

Black screen that never progresses past the boot logo

Almost always a mismatch between the display type and what the guest's boot loader or installer expects. Switching to std for the install itself, then to virtio once the OS and its drivers are in place, fixes this in most cases.

Resolution stuck at 1024x768 with no resize option

Classic symptom of the std display type without a SPICE agent or VirtIO-GPU driver running in the guest. Standard VGA supports higher fixed resolutions if you set them manually inside the guest, but it never does dynamic resizing.

SPICE console won't open, or the downloaded .vv file does nothing

This means there's no SPICE client on the machine you're connecting from — a browser can't render SPICE on its own the way it can noVNC. Install virt-viewer and try again.

Changed the display type but nothing looks different

You rebooted the guest instead of stopping and starting the VM from Proxmox. Go back and run a full qm stop followed by qm start.

Troubleshooting

If you've restarted the VM properly and it's still misbehaving, work through these in order.

1. Confirm the change actually saved: run qm config <vmid> again and check the vga line matches what you expect.
2. Confirm the VM was fully stopped before you started it — check Summary for a grey, stopped status rather than a fast click-through that might not have completed.
3. For Windows guests on virtio, make sure the VirtIO driver ISO is installed. Windows has no built-in driver for VirtIO-GPU, so without it you get a generic low-resolution fallback rather than a clean black screen — still not a working display.
4. For persistent SPICE resolution problems, check that spice-vdagent on Linux, or the SPICE guest tools service on Windows, is actually running, not just installed once and forgotten.
5. On a GPU-passthrough VM, set Display to none. A virtual display fighting with a passed-through physical GPU is a common source of confusing dual-output behavior and stray console windows.

Best Practices

• Use std for OS installers when you're not sure yet what the guest supports — it's the safest fallback and works almost everywhere.
• Switch to virtio for day-to-day Linux VMs once the OS is installed and running, for better resolution support with zero extra setup on modern distros.
• Use SPICE (qxl) with a real SPICE client when you want a genuinely interactive desktop session, not just the browser console for quick checks.
• Set none on headless server VMs and on anything using GPU passthrough.
• Always do a full stop and start after changing the display type. A guest reboot alone won't apply it, and it's the single most common reason people assume the change "didn't work."

Honestly, most homelab users overthink this setting. Unless you have a specific reason to change it, std during install and virtio afterward covers the large majority of cases without any fuss.

Frequently Asked Questions

Do I need to reinstall the OS after changing the display type?

No. It's a virtual hardware change, not a disk change — your data and installed OS are untouched. You just need to stop and start the VM.

Which display type is best for a Windows VM?

VirtIO with the VirtIO driver ISO installed, or SPICE with the SPICE guest tools if you want dynamic resolution and clipboard sharing. Skip VMware compatible unless you're specifically chasing a driver issue.

Can I use GPU passthrough and a virtual display at the same time?

Technically yes, but it usually causes more confusion than it's worth. Set Display to none once passthrough is working, so there's only one display source to think about.

Why does my console freeze even though the VM is still running?

The console view and the VM itself are separate things. Check CPU and network activity on the Summary tab — if it's active, the VM is fine and it's just the display connection that's stuck. Closing and reopening the console tab usually clears it.

Is VirtIO-GPU (GL) worth turning on?

Only if you actually need 3D acceleration inside the guest, like running a desktop environment with animations. For a plain server VM it just adds host overhead for no real benefit.

Conclusion

The display type is one of those Proxmox settings that's invisible right up until it isn't. Once you know that std, virtio, qxl, and vmware are simply different virtual graphics cards — and that changing one means a full VM restart, not a guest reboot — black screens and stuck resolutions stop being a mystery and turn into a two-minute fix.

Next time a fresh VM hands you a blank console, check qm config before assuming something's actually broken. There's a decent chance it's just the wrong adapter for the job.