Can I use any Docker image as a WSL distribution?

Any Docker or OCI image with a Linux root filesystem can become a WSL distribution. Full OS images (Ubuntu, Fedora, Arch Linux) work best. Application-specific images (nginx, postgres) technically work but aren't designed for interactive use.

Do I need Docker installed to import container images into WSL?

No. You can use an OCI-compatible tool to download images directly via HTTP APIs, or use WSL UI which has a built-in OCI client. Docker or Podman makes the process easier but is not required for public registry images.

How do I import a Docker image into WSL without Docker?

WSL UI has a built-in OCI client that pulls images directly from registries without Docker. Alternatively, you can use tools like skopeo or crane to download images, extract the layers, and create a tar file for "wsl --import".

What container registries work with WSL imports?

Any OCI-compatible registry works: Docker Hub, GitHub Container Registry (ghcr.io), Quay.io, Microsoft Container Registry (mcr.microsoft.com), Amazon ECR Public, and private registries. Public images work without authentication; private images need login credentials.

Why do I need to set up a user after importing a container image?

Container images are designed to run as root by default. After importing into WSL, you should create a non-root user account, set a password, and configure /etc/wsl.conf to make that user the default login.

Importing Container Images as WSL Distributions

Most people install WSL distributions from the Microsoft Store — Ubuntu, Debian, Alpine, the usual suspects. But WSL can run any Linux filesystem. And you know what has a huge catalog of Linux filesystems ready to download? Container registries.

Every Docker image on Docker Hub, GitHub Container Registry, Quay.io, or any OCI-compatible registry is essentially a Linux root filesystem packaged in layers. You can pull any of them and turn them into a WSL distribution.

Want Fedora? Arch Linux? Rocky Linux? A minimal BusyBox environment? A pre-configured development image your team maintains? They're all available.

The Manual Way (With Docker or Podman)

If you already have Docker or Podman installed, the process is straightforward:

Step 1: Pull the Image

bash

docker pull archlinux:latest

Step 2: Create a Container and Export It

bash

docker create --name temp-arch archlinux:latest
docker export temp-arch -o C:\Temp\archlinux-rootfs.tar
docker rm temp-arch

This creates a container from the image (without starting it), exports its filesystem to a tar file, then removes the container.

Step 3: Import into WSL

powershell

wsl --import Arch "D:\WSL\Arch" C:\Temp\archlinux-rootfs.tar

Step 4: First Boot Setup

The imported distribution will log in as root. Set up a user account:

powershell

wsl -d Arch

bash

# Create a user (varies by distro)
useradd -m -G wheel myuser
passwd myuser

# Set default user in wsl.conf
cat > /etc/wsl.conf << 'EOF'
[user]
default=myuser
EOF
exit

powershell

wsl --terminate Arch
wsl -d Arch

The same approach works with Podman — just replace docker with podman in all commands.

Without Docker: The OCI Approach

You don't need Docker or Podman installed to pull container images. OCI (Open Container Initiative) images are just files hosted on HTTP APIs. You can download them directly.

How Container Images Work

A container image consists of:

A manifest — metadata describing the image, including its layers
Layers — gzipped tar files, each containing filesystem changes
A config — runtime settings (environment variables, entry point, etc.)

When you docker pull alpine, Docker fetches the manifest to learn what layers exist, downloads each layer, and stacks them on top of each other. That's all there is to it.

Click to expand

392 × 902px

Multi-Architecture Images

Most images on Docker Hub support multiple architectures (amd64, arm64, etc.). The manifest you first receive is actually a manifest list — an index pointing to architecture-specific manifests. For WSL, you want the linux/amd64 variant.

Layer Merging and Whiteouts

Container images use a layered filesystem. Each layer can add, modify, or delete files from the layers below it. Deletions are handled through whiteout files:

.wh.filename — deletes a specific file from lower layers
.wh..wh..opq — marks a directory as opaque, hiding all contents from lower layers

When building a rootfs for WSL, you need to process these whiteouts correctly. Simply extracting all layers on top of each other doesn't work — you'd end up with stale files that should have been deleted.

Why Not Just Extract on Windows?

There's a subtlety that trips people up: you can't extract Linux tar layers to a Windows filesystem and then import them. Linux symlinks, permissions, and special files don't survive the round-trip through NTFS. The layers need to be merged in tar format, keeping the Linux-native metadata intact, and then imported directly by WSL.

Popular Images to Try

Here are some container images that make useful WSL distributions:

Image	Why
`archlinux:latest`	Rolling release, AUR access, cutting-edge packages
`fedora:latest`	Latest Fedora release, good for Red Hat ecosystem
`rockylinux:9`	RHEL-compatible, great for enterprise dev work
`clearlinux:latest`	Intel-optimized, performance-focused
`amazonlinux:2023`	Match your AWS Lambda/EC2 environment locally
`oraclelinux:9`	Oracle database development and testing

Any image with a full Linux userspace works. Minimal images like alpine work too, though they use musl libc which can cause compatibility issues with some software.

Images that DON'T work well as WSL distributions:

scratch — empty image, nothing to run
busybox — too minimal, missing package manager
Application images (like nginx, postgres) — these are designed to run a single process, not be interactive environments

The Easy Way: WSL UI

WSL UI has a built-in OCI client that handles all of this without Docker, Podman, or any command-line work. The "New Distribution" dialog includes a Container tab where you can:

Browse a catalog of pre-configured container images
Enter any custom image reference (e.g., ghcr.io/myorg/myimage:latest)
WSL UI pulls the manifest, downloads layers, handles authentication (Bearer tokens for public registries), merges layers with proper whiteout handling, and imports the result

The built-in OCI client works for public registries. For private registries that need authentication beyond anonymous Bearer tokens, WSL UI can also delegate to Docker or Podman if they're installed — giving you the best of both worlds.

Progress is shown as each layer downloads, so you can see how far along the pull is for large images.

Registry Authentication

Public images on Docker Hub, GHCR, Quay.io, and MCR (Microsoft Container Registry) use a challenge-based authentication flow:

Client requests the manifest
Registry responds with 401 Unauthorized and a WWW-Authenticate header
Client requests a token from the auth service
Client retries with the Bearer token

This happens automatically for public images — no login required. Private images need credentials, which is where having Docker or Podman configured with docker login or podman login helps.

Post-Import Setup

Container images are designed for containers, not interactive use. After importing, you'll typically want to:

Create a non-root user — containers run as root by default
Install an init system — some distros need systemd configured in /etc/wsl.conf
Set up a package manager — most images have one, but verify it works
Configure locale and timezone — container images often have minimal locale support

For Ubuntu and Debian-based images:

bash

apt update && apt install -y sudo locales
locale-gen en_US.UTF-8
useradd -m -s /bin/bash -G sudo myuser
passwd myuser

For Fedora/RHEL-based images:

bash

dnf install -y sudo passwd
useradd -m -s /bin/bash myuser
passwd myuser
usermod -aG wheel myuser

Summary

Task	Command
Pull with Docker	`docker pull image:tag`
Export container	`docker create --name tmp image && docker export tmp -o rootfs.tar && docker rm tmp`
Import to WSL	`wsl --import Name "D:\path" rootfs.tar`
Set default user	Edit `/etc/wsl.conf` → `[user]` → `default=username`

Container registries are the largest library of Linux environments available. Combined with WSL's import command, you can run virtually any Linux distribution — not just the handful in the Microsoft Store.