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

docker pull archlinux:latest

Step 2: Create a Container and Export It

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

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:

wsl -d Arch

# 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

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:

1. A manifest — metadata describing the image, including its layers
2. Layers — gzipped tar files, each containing filesystem changes
3. 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.

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:

1. Browse a catalog of pre-configured container images
2. Enter any custom image reference (e.g., ghcr.io/myorg/myimage:latest)
3. 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:

1. Client requests the manifest
2. Registry responds with 401 Unauthorized and a WWW-Authenticate header
3. Client requests a token from the auth service
4. 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:

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

For Ubuntu and Debian-based images:

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:

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.

---

Originally published at https://wsl-ui.octasoft.co.uk/blog/importing-container-images-as-wsl-distributions