The Final Push to v0.1.0

After testing the provider on my corporate machine, I discovered a bug related to the missing Windows HOME environment variable. The provider was trying to cache files on a NAS drive (mapped as U:) instead of the local user directory. After fixing this by switching to Vagrant.user_data_path, I felt confident that v0.1.0 was nearly ready.

All that remained was a comprehensive test run across all available WSL distributions.

The –name Flag Mystery

While reading through the WSL help documentation, I noticed the –name flag for wsl –install. I was puzzled - what’s the point of this flag?

I had a distant memory from years ago: WSL would reuse existing VM disks when creating multiple instances. If you didn’t create a clean snapshot immediately after installation, the second VM would inherit changes from the first one. This was exactly why my provider prevents creating distributions from already-in-use WSL instances.

But if that’s true, what does the –name flag actually do?

Testing the –name Flag

Time to test this assumption. I created two Ubuntu 24.04 instances:

# First instance
wsl --install Ubuntu-24.04 --name Ubuntu-First --no-launch
wsl -d Ubuntu-First bash -c "echo 'Test file from first' > ~/testfile.txt"

# Second instance
wsl --install Ubuntu-24.04 --name Ubuntu-Second --no-launch
wsl -d Ubuntu-Second bash -c "ls -la ~/"

Result: The second instance was completely empty. No testfile.txt. Each instance has its own independent virtual disk.

Wow… I remembered wrong?

When Did This Flag Appear?

A quick search revealed the –name flag was added to WSL around 2023 (version 2.4.4), documented in microsoft/WSL#9210. The last time I worked extensively with WSL was around 2021-2022, when this flag didn’t exist yet - and Ubuntu 24.04 wasn’t available either.

Testing Legacy Distributions

But wait - what about older distributions like Ubuntu 20.04 and 22.04?

wsl --install Ubuntu-20.04 --name Ubuntu2004-Test --no-launch
# Result: Installation completes but distribution doesn't appear in wsl -l

wsl --install Ubuntu-20.04  # Interactive installation
# Now it appears in wsl -l

Discovery: Legacy distributions (Ubuntu 20.04/22.04, Oracle Linux) don’t properly register with the –no-launch flag. They require interactive setup with username/password prompts. Only modern distributions support the new registration system.

So I was right - but only for legacy distributions!

The Real Purpose: Caching

Even for modern distributions with the –name flag, there’s still value in caching. While each named instance creates an independent VM, the installation always downloads from the Microsoft Store.

My provider’s clean distribution cache speeds this up significantly - instead of repeated downloads, it creates one clean tar file locally and imports it with different names. Much faster for creating multiple instances.

The Great Multi-Distribution Test

Now for the marathon: testing all available WSL distributions with shell, file, and Ansible provisioners.

Success Stories

8 distributions working flawlessly:

  • AlmaLinux-8, AlmaLinux-9
  • Debian
  • FedoraLinux-42
  • Ubuntu, Ubuntu-24.04
  • Kali-Linux
  • openSUSE-Tumbleweed

The Problem Children

Legacy Distributions:

  • Ubuntu-20.04, Ubuntu-22.04
  • OracleLinux (all versions: 7.9, 8.10, 9.5)
  • Issue: –no-launch flag doesn’t register them properly
  • Require interactive setup (username/password)

Guest Detection Failures:

  • SUSE-Linux-Enterprise-15-SP6/SP7
  • Error: “The guest operating system of the machine could not be detected!”
  • File provisioner fails without guest capability

Bleeding Edge:

  • AlmaLinux-10, AlmaLinux-Kitten-10
  • Ansible provisioner fails: EPEL repositories don’t exist yet for these versions
  • Error: curl: (22) The requested URL returned error: 404 for EPEL

Minimal Distributions:

  • archlinux
  • Missing sudo by default - Ansible provisioner fails
  • Would need pacman -Sy –noconfirm sudo pre-provisioning

Shared Folder Issues:

  • openSUSE-Leap-15.6
  • Silent failure creating shared folders

v0.1.0: Good Enough for a PoC

I think this is sufficient for a proof-of-concept v0.1.0 release.

Working Features:

  • Create and manage WSL2 distributions through Vagrant
  • Standard commands: up, status, halt, destroy, ssh
  • Provisioners: shell, file, ansible_local
  • Synced folders
  • Clean distribution caching for faster deployment
  • 8 tested and working distributions

Still Untested:

  • CPU and memory limit configuration
  • Docker installation and container execution
  • Snapshot creation and restore
  • Network configuration
  • GUI application support (WSLg)

These would be good scope for v0.2.

Not Production-Ready, But a Solid Foundation

I wouldn’t recommend this for production yet, but it’s already a solid starting point for developers who need Vagrant-like workflows on WSL2.

Why Build This?

I’ll be honest: I’m not a fan of Microsoft-centric solutions. I’m building this plugin because developers - myself included - are increasingly forced to use WSL on Windows. Corporate environments, client requirements, and the Windows ecosystem all push us in this direction.

My hope is that this provider offers a smoother transition path for developers who find themselves in this situation. If you’re used to Vagrant workflows with VirtualBox or VMware, but now need to work with WSL2, this plugin aims to make that transition less painful.

The code is available on GitHub at https://github.com/LeeShan87/vagrant-wsl2-provider. Contributions, bug reports, and feedback welcome.

What’s Next?

v0.2 roadmap:

  • VirtualBox VM import support (convert existing Vagrant boxes to WSL2)
  • Resource limit testing (CPU/memory)
  • Docker-in-WSL2 workflows
  • Snapshot/restore functionality
  • Better error handling for legacy distributions

Stay tuned!