Docker Desktop and WSL2 Not Working on Snapdragon X? Fix It

Docker Desktop and WSL2 not working on your Snapdragon X laptop usually comes down to one thing most guides skip: these are two separate layers, and only one is actually broken. WSL2 itself runs well on Windows on ARM, while Docker Desktop’s ARM build is the part that throws “Unexpected WSL error” and refuses to start. Once you split the two, the fix is straightforward.

#Why Does WSL2 Work but Docker Desktop Fail on Snapdragon X?

Because they’re built for different things, and only one has a mature ARM build.

WSL2 is part of Windows itself. On a Snapdragon X machine you install it with one command, and it pulls down a native ARM64 Linux kernel and an ARM64 Ubuntu image. According to Microsoft’s WSL install documentation, running wsl --install installs Ubuntu and sets new distros to “WSL 2 by default.” In our testing on a Snapdragon X Plus unit, the ARM64 Ubuntu distro under WSL2 built and ran native Linux containers without platform errors.

Docker Desktop is a separate GUI app that sits on top of WSL2. Its Windows-on-ARM version is newer and far less finished. Docker’s own Windows install page lists the ARM download as “Docker Desktop for Windows - Arm (Early Access).” Early Access means exactly what you’d expect: it installs, but it’s prone to the WSL handshake failures people keep posting about.

So when you see WSL2 commands working in a terminal while Docker Desktop sits there with a red error, nothing is contradictory. The kernel layer is healthy. The beta app on top of it isn’t.

#The Two Layers, Side by Side

This table is the whole article in one glance. Match your symptom to the right layer before you change anything.

If your problem is in row 1, it’s a setup gap and easy to fix. If it’s row 2, the fix is to stop relying on Docker Desktop. If it’s row 4, you have an image architecture mismatch, covered further down.

#Step 1: Get WSL2 Running on ARM the Right Way

Start clean. A lot of “Docker won’t start” reports are really “WSL was never fully set up.”

Open PowerShell as administrator and enable the platform features Windows needs for WSL2. The Virtual Machine Platform is the one people forget, and without it WSL2 can’t run its lightweight VM.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart, then install WSL with the distribution in one go:

wsl --install -d Ubuntu

After the reboot, Ubuntu opens and asks you to create a Linux username and password. That’s your native ARM64 distro. The first launch decompresses files and can take a minute, which is normal per Microsoft’s documentation.

Now verify the stack. These two commands tell you almost everything:

wsl --version
wsl -l -v

wsl --version shows your WSL, kernel, and WSLg versions. wsl -l -v lists each distro with its WSL version, and you want to see VERSION 2 next to Ubuntu. If it says 1, convert it with wsl --set-version Ubuntu 2. If wsl --version errors out entirely, run wsl --update to pull the current build.

#Step 2: Choose Your Container Path

Here’s the decision that fixes the actual problem. You have two real options on Snapdragon X, and the GUI is the weaker one.

Option A, Docker Engine inside WSL (recommended). Skip Docker Desktop and install the Linux Docker daemon directly in your Ubuntu distro. This is plain native arm64 Docker, the same thing that runs on a Raspberry Pi or an ARM server, so it doesn’t depend on the Early Access Windows GUI at all. Inside the Ubuntu terminal:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Close and reopen the terminal, then run docker run hello-world. Because you’re on an ARM64 host pulling an arm64 image, it just works. In our testing on Snapdragon X, we built and ran native arm64 containers this way with no WSL handshake errors, the exact failure mode Docker Desktop kept hitting on the same machine.

That’s the same native-ARM advantage that lets apps like Photoshop run on Snapdragon X at full speed when there’s a real ARM64 build.

Option B, Podman. If you’d rather avoid the Docker daemon entirely, Podman runs rootless and ships in Ubuntu’s repos: sudo apt install podman. The docker command syntax mostly carries over, so podman run hello-world behaves the same.

Both options give you native arm64 containers without fighting a beta GUI. If you specifically need the Docker Desktop dashboard, you can still try it, but treat it as optional and expect rough edges. This mirrors the broader ARM reality covered in our guide to Windows on ARM app compatibility, where native builds beat emulated or beta ports every time.

#Why Do My linux/amd64 Containers Fail or Run Slowly?

Because your laptop’s CPU is ARM64, and x86 container images don’t run on it natively.

A huge number of images on Docker Hub are built for linux/amd64, the x86 architecture. On a Snapdragon X host, Docker can only run those through QEMU emulation, a software CPU translation layer. When the emulation layer isn’t set up, you get the classic exec format error. When it’s set up, the container runs, just noticeably slower because every instruction is being translated.

This is the same principle behind how Windows itself runs x86 desktop apps on these chips. According to Microsoft’s explanation of how emulation works on Arm, the Prism emulator works by “just-in-time compiling blocks of x86 instructions into Arm64 instructions.” Containers use a different translator, QEMU rather than Prism, but the tradeoff is identical.

It works, and it costs you speed. If you want the chip-level side of this, our Snapdragon X versus Intel Core Ultra versus AMD Ryzen AI breakdown explains where ARM gives and takes.

Two practical rules:

• Prefer multi-arch images. Official images like node, python, postgres, and nginx publish an arm64 variant, so Docker grabs it automatically and runs native.
• When you must run an x86-only image, pin the platform explicitly with docker run --platform linux/amd64 imagename so you know emulation is in play, and accept the slowdown.

For comparison, hypervisors hit the same wall in a different way. Full virtual machines can’t run x86 guests on ARM Windows either, which we cover in running VirtualBox or VMware on Snapdragon X.

#When WSL Itself Throws Errors

Work through these in order. Most “Unexpected WSL error” cases clear up at step 2 or 3.

1. Update WSL. Run wsl --update in PowerShell, then wsl --shutdown to restart the subsystem cleanly.
2. Confirm virtualization is on in firmware. Snapdragon X ships with it enabled, but a BIOS reset can turn it off. WSL2 needs the Virtual Machine Platform feature plus hardware virtualization.
3. Reinstall the distro if it’s corrupted. wsl --unregister Ubuntu wipes it, then wsl --install -d Ubuntu gives you a fresh ARM64 image. Back up anything in the Linux home folder first.
4. Check your WSL version against Docker’s floor. Docker’s WSL2 backend documentation states that you need “at a minimum WSL version 2.1.5” for Docker Desktop to behave.

If WSL2 commands now work but Docker Desktop still fails, that’s your signal to switch to Docker Engine in WSL. You’ve proven the kernel layer is fine, so stop debugging the beta GUI. Knowing why these ARM machines behave differently helps, and our explainer on what a Copilot+ PC is covers the platform basics.

#Bottom Line

On a Snapdragon X laptop, install WSL2 with a native ARM64 Ubuntu distro, then run Docker Engine directly inside that distro for native arm64 containers. Treat Docker Desktop for Windows on ARM as optional and beta, because its Early Access state is what generates the WSL errors, not WSL2 itself. If you only ever hit x86-only images, expect QEMU emulation and the slowdown that comes with it, or find a multi-arch alternative.

#Frequently Asked Questions