You just flashed the Proxmox VE ISO to a USB stick, booted the installer, and now you're stuck typing your root password wrong three times in a row. The "z" key keeps producing a "y." The "@" symbol won't show up no matter what you press. Nothing about your keyboard is broken — Proxmox is just reading it with the wrong layout.
Here's the part that trips people up: this isn't one setting. It's three separate ones, in three separate places, and each behaves differently. There's the layout the installer itself uses, the layout the Datacenter applies to every noVNC console in the web UI, and the layout the guest operating system inside your VM thinks it's using. Fix the wrong one and nothing changes, so you end up guessing.
This guide walks through all three, in the order you're likely to hit them: during install, in the web console right after, and inside a freshly created VM or container.
What You Will Learn
- Why keyboard layout problems happen in three different places instead of one
- How to set the correct layout during the Proxmox VE ISO installation
- How to change the host's physical console (TTY) layout after install
- How to set the Datacenter-wide noVNC keyboard layout, and override it per VM
- How to fix the layout inside a Linux or Windows guest itself
- Where SPICE and the serial console behave differently from noVNC
What Is This Feature?
Proxmox VE runs on Debian, and Debian keeps track of keyboard layout at the operating system level using a package called keyboard-configuration. That's what controls the physical keyboard plugged into the server itself — the one you'd use at a local monitor, or over IPMI/iKVM.
Separately, the Proxmox web interface has its own setting for the noVNC console — the browser-based screen you get when you click Console on a VM. This lives in Datacenter → Options → Keyboard Layout, and it's stored in a file called /etc/pve/datacenter.cfg as a single line: keyboard: en-us (or whichever layout you pick). This setting tells Proxmox how to translate the key presses your browser sends into scancodes the VM understands.
And then there's a third layer: the guest operating system running inside the VM has its own idea of what layout it's using, completely independent of Proxmox. A Debian VM has its own keyboard-configuration settings. A Windows VM has its own language and keyboard settings under Windows itself.
None of these three layers know about each other. They just have to agree, or you get garbled input.
Why Would You Use It?
If you've only ever used a US English keyboard, you may never run into this. But the second you're on a German QWERTZ board, a French AZERTY layout, or anything with different symbol placement, mismatches become a daily annoyance rather than a one-time setup step.
It also matters more than people expect for security. Typing a long, random root password blind through a wrong layout is genuinely painful — you can't see the password field, autocorrect doesn't exist, and a single wrong symbol locks you out. Getting the layout right before you set that password saves you a reinstall.
Homelab users hit this constantly because they're often installing from a laptop with one layout, connecting to a server with another, and then remoting in from a third machine at work. Each of those is a separate opportunity for a mismatch.
Prerequisites
- A Proxmox VE host — this guide covers both a fresh install and an already-running Proxmox VE 9.x system
- Root or admin access to the Proxmox web interface (or physical/IPMI console access for TTY-level fixes)
- Know which physical layout you're actually using — QWERTY (US), QWERTZ (Germany, Austria, Switzerland), AZERTY (France, Belgium), or another regional layout
- A basic comfort level with the Proxmox web UI; no scripting experience needed for most of this
Step-by-Step Tutorial
1. Setting the layout during installation
On the "Location and Time Zone" screen of the installer, Proxmox asks for your Country, Time Zone, and Keyboard Layout. Country is used partly to pick a nearby download mirror, and it also pre-fills a guess for keyboard layout — but that guess is often wrong, especially on multi-language countries like Switzerland or Belgium.
Check the Keyboard Layout dropdown on this screen and change it manually if it doesn't match your physical keyboard. Don't just trust the auto-fill. This is the single most common place people get burned, because it's easy to click through this screen without reading it.
If you're already past this screen and typing garbage into the password field, you can restart the installer rather than fighting through it — nothing has been written to disk yet at that point.
2. Fixing the host's physical console layout after install
This is the layout used when you're sitting at the server with a real monitor and keyboard, or connected through IPMI/iKVM. It's controlled by Debian's console-setup tooling, separate from anything in the Proxmox web UI.
Open a shell (either at the physical console, over SSH, or through the Proxmox Shell button in the web UI) and run:
dpkg-reconfigure keyboard-configurationThis opens an interactive menu. Pick your keyboard model (Generic 105-key is fine for most people), then your layout, then variant. When it finishes, apply the change without rebooting:
setupconIf setupcon doesn't seem to take effect on your current session, log out and back in, or just reboot the host — it's a quick operation and won't affect running VMs.
3. Setting the Datacenter-wide noVNC layout
This is the one most people actually need, since it's what governs every VM's browser-based console by default. In the web UI, go to Datacenter, click Options, and double-click Keyboard Layout. Pick the layout that matches the keyboard on the machine you're using to browse to Proxmox — not the server's physical keyboard, and not the guest's.
That distinction matters and it's worth repeating: this setting is about your browser's input, not the server's hardware. If you're on a German laptop RDP'd into a US-layout workstation to reach Proxmox, you need to match whatever keyboard is physically producing the keystrokes when you click into the console window.
You can also set this directly by editing the config file, which is handy if you're scripting a new install:
echo "keyboard: de" >> /etc/pve/datacenter.cfg4. Overriding the layout for a single VM
Sometimes you want one VM to use a different layout than everything else — maybe it's a Windows box you only ever access from a specific workstation. Select the VM, go to its own Options tab, and look for Keyboard Layout there. Leaving it on "Default" makes it inherit the Datacenter setting; changing it applies only to that VM's console.
5. Fixing the layout inside the guest operating system
The Datacenter and VM-level settings only control how Proxmox translates your keystrokes into scancodes. They don't touch what the guest OS itself thinks its layout is. If those two disagree, you'll still get wrong characters even with steps 3 and 4 done correctly.
Inside a Debian or Ubuntu VM or LXC container, run the same command as on the host:
dpkg-reconfigure keyboard-configurationfollowed by setupcon. On an LXC container you can run this straight from the console without needing to reboot the container.
Inside a Windows VM, this has nothing to do with Proxmox at all — open Settings, then Time & Language, then Language & Region, and add or switch the keyboard layout there, same as you would on any physical Windows PC.
Commands Explained
| Command | What it does |
|---|---|
dpkg-reconfigure keyboard-configuration | Opens an interactive menu to set the keyboard model, layout, and variant for the current Linux system — works the same on the Proxmox host, a Debian/Ubuntu VM, or an LXC container. |
setupcon | Applies the keyboard-configuration changes to the current console session immediately, without a reboot. |
cat /etc/default/keyboard | Shows the currently stored layout settings (XKBLAYOUT, XKBMODEL, XKBVARIANT) so you can confirm what's actually configured. |
localectl status | Displays the system's current locale and virtual console keymap settings — useful for a quick sanity check on a systemd-based host. |
Common Errors
The classic symptom is typing "y" and getting "z," or the reverse — the telltale sign of a QWERTY/QWERTZ mismatch. On French AZERTY keyboards, the letters A and Q, or Z and W, are the ones that swap.
Another common one: the "@" symbol doesn't appear at all when you press AltGr+2 or AltGr+Q, because the noVNC layout doesn't match your physical keyboard's AltGr combinations. This is especially common for German and other non-US layouts where symbols live behind AltGr.
You might also see this in the installer specifically: the password field shows dots so you can't visually confirm what you typed, you set a password with a layout mismatch, and then the very next screen — confirm password — fails because you can't reproduce the same wrong characters twice. If that happens, just go back and fix the keyboard layout dropdown first.
Troubleshooting
When something's off, it helps to figure out which of the three layers is actually wrong before you start changing settings. Ask yourself where the bad character is happening: at the installer, at the login screen for the Proxmox web UI itself (that's just your browser and OS, nothing to do with Proxmox), in a VM's noVNC console, or after you've already logged into the guest OS.
The console type you're using also changes the behavior:
| Console type | How it handles keyboard layout |
|---|---|
| noVNC (default browser console) | Uses the Datacenter or VM-level keyboard setting to translate keys into scancodes. Most prone to mismatches. |
| SPICE | Sends more raw input through the virt-viewer client, so it's generally less sensitive to the Datacenter setting — but the guest OS still needs its own layout configured correctly. |
| Serial console (VM with a serial port configured) | Text-based, so it sidesteps scancode translation issues almost entirely. A handy workaround while you sort out the real fix. |
If you're stuck mid-install and can't reach a Keyboard Layout dropdown, some installer versions let you drop into a debug shell (check the boot menu) where you can run loadkeys for the installer environment itself — though for most people, just restarting the installer and picking the right layout on the Location screen is faster.
One more thing worth checking: if you recently upgraded Proxmox VE and your host console layout suddenly reverted, it's usually because console-setup.service didn't get restarted. A reboot clears it up.
Best Practices
Set the Datacenter keyboard layout once, right after install, before you create any VMs — it saves you from fixing every individual console later. Match it to the keyboard on the machine you'll normally be administering Proxmox from, not the server hardware.
If you manage Proxmox from more than one location with different physical keyboards, the serial console is worth setting up for at least one VM as a layout-independent fallback. It's not glamorous, but it works when nothing else will.
Document the layout you chose somewhere outside Proxmox itself — a wiki page, a README, whatever you actually use. Six months from now you won't remember whether you set "de" or "de-ch," and the difference matters for the Y/Z and symbol keys.
Frequently Asked Questions
Does changing the Datacenter keyboard layout affect existing VMs?
Yes, any VM still set to "Default" for its own Keyboard Layout option will immediately pick up the new Datacenter-wide setting. VMs with their own explicit override are unaffected.
Why does my keyboard work fine in SPICE but not in noVNC?
SPICE passes more of the input through directly rather than relying on Proxmox's scancode translation table, so it's less sensitive to a Datacenter/browser layout mismatch. noVNC depends entirely on that setting being correct.
I set the correct layout everywhere and it's still wrong. What's left?
Check the guest OS itself. Proxmox-level settings only control translation up to the VM's virtual keyboard — if the operating system inside still thinks it's on a different layout, you'll need to fix that separately with the guest's own settings.
Can I set a different layout for each individual VM?
Yes. Each VM's Options tab has its own Keyboard Layout field. Leave it on Default to inherit the Datacenter setting, or pick a specific layout to override it for that one VM.
Does this affect LXC containers too?
The Datacenter/noVNC setting applies to the container console the same way it does for VMs. Inside the container itself, fix the layout with dpkg-reconfigure keyboard-configuration just like you would on the host.
Conclusion
Keyboard layout issues in Proxmox VE aren't a bug — they're just three independent settings that happen to look like one problem from the outside. Once you know which layer you're actually fighting (installer, Datacenter/noVNC, or guest OS), the fix is usually a two-minute dropdown change or a single dpkg-reconfigure command.
Get the Datacenter setting right early, and most of this disappears before it ever becomes annoying. The rest is just knowing where to look when a specific VM or the installer itself misbehaves.