Skip to content
WSLDeep Dive Published Updated 3 min readViews unavailable

WSL Export and Import: What a tar Archive Preserves and What Registration Adds

A forensic WSL migration guide separating Linux root-file-system contents from Windows registration, launcher identity, default user, VHD state, and secrets.

wsl --export captures a registered distribution into a tar archive by default, while wsl --import creates a new Windows registration and root file system from an archive. The archive represents the Linux file-system tree WSL exports; it is not a full image of Windows registration, Store app identity, host networking, Terminal profiles, credentials, or external Windows-mounted data.

Freeze a coherent source

Stop databases and applications cleanly, flush in-progress package transactions, and terminate the distribution before export:

wsl --list --verbose
wsl --terminate Ubuntu-Work
wsl --export Ubuntu-Work D:\Backups\Ubuntu-Work-2026-08-09.tar
Get-FileHash D:\Backups\Ubuntu-Work-2026-08-09.tar -Algorithm SHA256

Use an approved destination with enough space and access controls. A tar archive can contain SSH material, shell histories, tokens, databases, and personal files. Encrypt and restrict it like the account it can reconstruct. Check the command’s exit status and hash after transport.

Mounted Windows drives under /mnt are not part of the distribution’s root-file-system ownership in the same way and should have their own backup. External mounts, network shares, USB devices, and host-side Docker/IDE state also need explicit inventory.

Tar and VHD exports have different goals

The tar path is portable for importing a root file system and lets WSL reconstruct a fresh VHDX. WSL also supports VHD export/import options on current versions, preserving a virtual disk representation and enabling --import-in-place workflows. A VHD remains tied to filesystem integrity and storage behavior and should be copied only while detached.

Do not infer generic tar behavior from tar.exe alone. WSL’s exporter is responsible for representing Linux ownership, modes, symbolic links, special metadata, and other supported content. Verify the attributes your workloads require after import, especially extended attributes, capabilities, hard links, case-sensitive names, sparse files, and socket/device exclusions.

Import creates new host registration

wsl --import Ubuntu-Restore D:\WSL\Ubuntu-Restore \
  D:\Backups\Ubuntu-Work-2026-08-09.tar --version 2
wsl --distribution Ubuntu-Restore --user root

The name and install location are new Windows-side choices. Store launcher metadata, Start-menu identity, app updates, Windows Terminal profile GUID, per-distro firewall entries, and integrations keyed to the old name do not automatically follow. An imported distribution commonly starts as root until its default user is configured through /etc/wsl.conf or a launcher/import-specific supported mechanism.

The Linux /etc/passwd, groups, home directories, packages, /etc/wsl.conf, and system configuration are inside the root file system. Verify the intended user exists before setting it as default. Machine IDs, SSH host keys, cloud-init state, and service identity may also have been copied; cloning them onto two simultaneous instances can create collisions. Regenerate only according to each service’s documented clone procedure.

Acceptance is a restore, not an archive listing

Import under a temporary unique name without unregistering the source. Test file ownership/modes, symlinks, extended attributes/capabilities required by applications, Git case behavior, package database, systemd units, network, DNS, interop, default user, container data, databases, and secrets. Reboot Windows and test again.

Only after the restore passes should automation and Terminal/IDE integrations move to the new registration. wsl --unregister permanently removes a distribution; do not use it as “cleanup” until backup and restored workloads are independently verified.

A WSL export is valuable because it separates Linux state from a particular VHD. A complete migration manifest adds the host-side registrations and external dependencies that the tar was never designed to contain.

Related:

Sources:

Comments