Skip to main content

Running in a Virtual Machine

James Herring
Updated

Running in a Virtual Machine

If you are installing Docker Desktop, Rancher Desktop, or Podman Desktop inside a virtual machine (VM) -- for example, a VMware guest, a Hyper-V guest, a VirtualBox guest, or a cloud-hosted VM -- you may encounter errors during installation or when starting the application. This is caused by a requirement called nested virtualisation.

This article explains why the problem occurs, how to diagnose it, and how to resolve it.

Why This Happens

Docker Desktop and Rancher Desktop both need a hypervisor to run Linux containers on Windows:

  • WSL 2 is the default backend on Windows. It runs a lightweight Linux kernel, but it relies on Hyper-V under the hood.
  • Hyper-V is the alternative backend on Windows Pro, Enterprise, and Education editions.

When your Windows installation is itself running inside a virtual machine, enabling WSL 2 or Hyper-V means running a hypervisor inside a hypervisor. This is called nested virtualisation, and it only works if the outer (host) hypervisor explicitly allows it.

If the host hypervisor does not expose hardware virtualisation extensions (Intel VT-x or AMD-V) to the guest VM, WSL 2 and Hyper-V cannot start, and Docker Desktop or Rancher Desktop will fail.

Common Error Messages

You may see one or more of the following when attempting to install or start Docker Desktop or Rancher Desktop in a VM:

  • "Hardware assisted virtualization and data execution protection must be enabled in the BIOS"
  • "WSL 2 requires an update to its kernel component" or WSL 2 fails to start
  • "WSL2 is unable to start since virtualization is not enabled on this machine", often accompanied by error code Wsl/InstallDistro/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED
  • Docker Desktop is stuck on "Starting the Docker Engine..." indefinitely, or reports "Virtualization support not detected" even after enabling Windows features
  • The Hyper-V feature cannot be enabled in Windows Features
  • Rancher Desktop fails with virtualisation-related errors
  • "Please enable the Virtual Machine Platform Windows feature"

How to Check for Virtualisation Support

Windows

Open PowerShell or Command Prompt inside the VM and run:

systeminfo

Scroll to the bottom and look for the Hyper-V Requirements section:

Hyper-V Requirements:      A hypervisor has been detected. Features required for Hyper-V will not be displayed.

If you see this message, it means the VM is aware that it is running inside a hypervisor, but virtualisation extensions may not be passed through. If the section lists individual requirements and any of them say No, nested virtualisation is not enabled.

Linux

If you are running a Linux VM and want to verify virtualisation support:

grep -cE '(vmx|svm)' /proc/cpuinfo

A result of 0 means no virtualisation extensions are available to the guest.

Solutions

The most common fix is to configure the host hypervisor (the software managing the outer VM) to pass through virtualisation extensions to the guest.

VMware Workstation or VMware Fusion

  1. Shut down the VM
  2. Open the VM settings
  3. Navigate to Processors (or Processors & Memory on Fusion)
  4. Tick Virtualize Intel VT-x/EPT or AMD-V/RVI
  5. Save and restart the VM

VMware ESXi / vSphere

  1. Shut down the VM
  2. Edit the VM settings in the vSphere Client
  3. Go to CPU settings
  4. Tick Expose hardware assisted virtualization to the guest OS
  5. Save and power on the VM

Alternatively, add vhv.enable = "TRUE" to the VM's .vmx configuration file.

Note: Nested virtualisation on ESXi requires ESXi 6.5 or later and a host CPU with VT-x/EPT support.

Hyper-V (Windows Host Running the Outer VM)

Open PowerShell as Administrator on the host machine (not inside the VM) and run:

Set-VMProcessor -VMName "YourVMName" -ExposeVirtualizationExtensions $true

Replace "YourVMName" with the name of your virtual machine. Then restart the VM.

VirtualBox

VirtualBox has limited support for nested virtualisation and it is not reliable for running Docker Desktop or Rancher Desktop. If you are using VirtualBox, consider switching to VMware Workstation or Hyper-V as the host hypervisor, or use Solution 2 below.

Cloud-Hosted VMs

Not all cloud VM types support nested virtualisation. Check the following guidance for your provider:

Cloud Provider Nested Virtualisation Support
Microsoft Azure Not supported on B-series (burstable), Av2, or Dv2. The burstable B-series (e.g. B2ms) is the most common pitfall because it is the cheapest default — if Docker Desktop fails to start on an Azure VM, check the size first. Confirmed working on Intel Dsv5/Esv5 (e.g. Standard_D2s_v5) and AMD Easv3 (e.g. Standard_E2as_v3). Microsoft's official guidance lists Dv3/Ev3 Intel and newer as supported; AMD support varies by sub-series and generation, so verify the specific SKU against Microsoft documentation or by attempting wsl --install -d Ubuntu on the VM. For a low-cost Windows host, start with Standard_D2s_v5 or larger.
Google Cloud (GCP) Supported on VMs with Haswell or newer CPUs. Enable with --enable-nested-virtualization when creating the instance.
Amazon Web Services (AWS) Standard EC2 instances do not support nested virtualisation. Use bare-metal instances (instance types with a .metal suffix) or use Solution 2.

After enabling nested virtualisation, restart the VM and retry the Docker Desktop or Rancher Desktop installation.

Solution 2: Use a Linux VM with Docker Engine Instead

If you cannot enable nested virtualisation -- or if your VM is already running Linux -- you can bypass the problem entirely by installing Docker Engine directly on a Linux operating system.

Docker Engine on Linux does not require a hypervisor. It uses Linux kernel features (namespaces and cgroups) to run containers natively, so nested virtualisation is not needed.

This is the simplest and best-performing option when a Linux VM is available.

Quick Install on Ubuntu / Debian

# Install Docker Engine
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (avoids needing sudo for docker commands)
sudo usermod -aG docker $USER

# Log out and back in for the group change to take effect, then verify
docker --version
docker compose version

Once Docker Engine is installed, Precision Bridge can be started normally with docker compose.

Solution 3: Use a Remote Docker Host

If neither of the above solutions is possible -- for example, you cannot modify the host hypervisor settings and must use a Windows VM -- you can run Docker on a separate machine and connect to it remotely.

On a remote Linux server with Docker Engine installed, configure Docker to accept remote connections (secured with TLS). Then, on the VM where you are working:

# Point the Docker CLI at the remote Docker daemon
export DOCKER_HOST=tcp://your-docker-host:2376
export DOCKER_TLS_VERIFY=1

# Docker commands now execute on the remote host
docker compose up

This allows you to use the Docker CLI locally while containers run on a machine that natively supports Docker. Note that this approach introduces network latency and requires network connectivity between the VM and the Docker host.

Hosting on a Windows Server VM

Windows Server is a separate set of constraints on top of nested virtualisation. Even on a VM size that exposes nested virt correctly (so WSL 2 and Docker Desktop can install), the GUI-related components Precision Bridge depends on are not part of the default Server image. Plan to install all of the following on a fresh Windows Server VM before running Precision Bridge:

  • Microsoft Visual C++ Redistributable 2015–2022 (x64) — required by the embedded WebView2 control. Available from Microsoft.
  • Server-Media-Foundation Windows feature — Install-WindowsFeature Server-Media-Foundation in an elevated PowerShell. WebView2 silently refuses to launch without it.
  • Microsoft Edge WebView2 Runtime — install the Evergreen Standalone Installer (x64) from Microsoft as Administrator so the runtime is registered machine-wide. The smaller "Evergreen Bootstrapper" can silently fail to fetch the payload on a locked-down Server VM.
  • Desktop Experience SKU — Server Core has no GUI subsystem and is not supported.

Known limitation: embedded WebView2 on Windows Server

Even with every prerequisite installed, the embedded WebView2 window can fail to initialise on some Windows Server VMs (confirmed on Windows Server 2025 Desktop Experience). The symptoms are:

  • The native build launches but shows a blank white window. The FastAPI server is still serving correctly, so the UI is reachable at http://localhost:7500 from any browser on the VM.
  • The Windows manager (used to provision the Docker containers on first run) launches blank, then crashes on close with 'NoneType' object has no attribute 'BrowserProcessId'. There is no browser-fallback path today, which makes first-run container provisioning effectively blocked on these VMs.

If you encounter this on a Server VM:

  • For the native build, open http://localhost:7500 in a browser on the server as a workaround.
  • For the Docker install, switch to a Linux VM with Docker Engine (see Solution 2 above). This avoids the Windows manager and the WebView2 dependency entirely.

For any new production deployment to a cloud VM, a Linux VM with Docker Engine is the recommended path — it has none of the Windows Server hosting caveats and runs the same Precision Bridge containers.

Choosing a Solution

Situation Recommended Solution
Windows or macOS VM on VMware or Hyper-V, and you can change host settings Enable nested virtualisation on the host
Cloud VM on Azure (Dv3+) or GCP Enable nested virtualisation in cloud settings
Linux VM (any hypervisor) Install Docker Engine directly -- no nested virtualisation needed
Cloud VM on AWS (non-metal), Azure B-series, or older Azure series Resize to a nested-virt-capable SKU, or switch to a Linux VM and install Docker Engine
Windows Server VM (any provider) where the Windows manager or native build will not render Install the Windows Server prerequisites above; if the embedded window still fails, use the native build via http://localhost:7500 or switch to a Linux VM with Docker Engine
VirtualBox VM Switch hypervisor to VMware/Hyper-V, or use a Linux VM with Docker Engine
Cannot modify host settings at all Use a remote Docker host

Further Reading

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk