Import/Export docu missing info, outdated, poor quality.

JonathanDotCel commented 7 months ago

Documentation Issue

https://learn.microsoft.com/en-us/windows/wsl/basic-commands#import-and-export-a-distribution

wsl --import-in-place isn't available in 20H2
There's no indication when that option was ever available
There's no indication of where would be by default when using wsl --import
wsl --import does not support the suggested --vhd flags
wsl --export does not support the suggested --vhd flags
The WSL binary spits out a list of supported commands and params every time there's an issue, making it annoying as all hell to find the error message.
The error message is in no way highlighted (red, anyone?)
This documentation has the same issues as the git page.

Generally frustrating, low effort, poor quality documentation.

Link to documentation page

https://learn.microsoft.com/en-us/windows/wsl/basic-commands#import-and-export-a-distribution

Suggested Improvements

Address some of the issues mentioned in the first part of the form:

what happened to --import-in-place
what's up with the --vhd option
where's the default install location
tidy up the binary output

mattwojo commented 7 months ago

@JonathanDotCel I'm sorry you've found this frustrating. I can assure you that it's not low effort. :) Always appreciate issues like this to help us improve. In this particular case, my machine is still showing these command to work.. could you try running wsl --update to ensure that you've got the latest version of WSL? I believe that these commands should all still be supported, but investigating further.

JonathanDotCel commented 7 months ago

Hi Matt! Cheers for getting back.

Okay, so after updating WSL, the following happened. Thought it might be worth sharing a user experience, so I documented the process.

PS D:\wsl> wsl --export --vhd Ubuntu testfile.vhdx
Export in progress, this may take a few minutes.
This operation is only supported by WSL2.
Error code: Wsl/Service/WSL_E_WSL2_NEEDED
PS D:\wsl>

Issue: "Export in progress, this may take a few minutes". This is not true. Many posts covering this.

Issue: "Export in progress" appears before checks have completed. Suggests sloppy code behind the scenes.

Issue: It's not clear about what operation is only supported by WSL2. Is it the --vhd flag or is it the entire --export feature

   Removing the `--vhd` flag in this case does revert it back to working behaviour. But it doesn't *say* that.

Issue: Can this only be performed on a WSL2 image? Or is it available to WSL1 & WLS2 images, so long as you have WSL2 installed? Is it possible for example to export a WSL2 image and import it as WSL1?

TLDR; Whether someone's following an online guide or actually reading the docs, they're getting misleading feedback.

I appear to have WSL2, but it's still not working so I try a few version-specific commands to see what sticks.

wsl --set-default-version 2 This succeeds It accepts "2" as a version. It does not accept "3", "4", "5", etc, so it's definitely being validated

Issue: No warning that WL2 is not installed. Is it installed? I mean, it's behaving like it. At this point it's understandably quite confusing.

Still no --vhd though. I try a few more things:

wsl --set-version Ubuntu 2`

"For information on key differences with WSL 2 please visit https://aka.ms/wsl2
Conversion in progress, this may take a few minutes.
Failed to start virtual networking - please install the optional component Virtual Machine Platform by running: wsl.exe --install --no-distribution
Error code: Wsl/Service/CreateVm/WSL_E_VIRTUAL_MACHINE_PLATFORM_REQUIRED"

I had already installed the Virtual Machine platform and restarted, so ran this as instructed: wsl.exe --install --no-distribution

This appeared to be the missing step. Assuming this would affect the platform req only and not Error code: Wsl/Service/WSL_E_WSL2_NEEDED I repeated the previous command. Not expecting to be locked into an exceptionally long conversion process, without confirmation. (Note: It feels like I got this bit wrong. I'm hoping I misremembered this step, I may well have, it doesn't make much sense to me, but this is how I remember it.)

wsl --set-version Ubuntu 2

Issue: -- No confirmation request? -- No backup reminder? -- No "This will irreversably convert your WSL instance...are you sure?" before continuing. -- No warning that this could potentially take hours, not minutes. No respect for user's time. -- No explanation of the consequences of performing the action, at all.

Issue: After an hour I cancelled the operation, got stuff to do. No warning, no progress, no estimates, etc.

So eventually I just deregister this install, and reimport it. I test it to ensure things work nicely, they do.

Later, when I have more time, I try to repeat:


For information on key differences with WSL 2 please visit https://aka.ms/wsl2
Conversion in progress, this may take a few minutes.
The distribution is already the requested version.
Error code: Wsl/Service/WSL_E_VM_MODE_INVALID_STATE

i.e. this time around, it just imported it as a WSL2 image.

Issue: At no point did it ask, or say, which version of WSL it was about to use when I reimported after updating WSL.

Maybe cruel to call it low effort, but I stand by what I said about it being not the best quality web docu or binary feedback. It got there in the end, without --vhd, and without WSL2... But at every stage of the process, something else was vague, frustrating, poorly explained, or misleading, with unexpected outcomes. Between this VSCode and Windows itself, I've wasted another Saturday night chasing down MS issues which should not exist, I'm sure you'll understand, it's incredibly grating.

Thanks, J

craigloewen-msft commented 7 months ago

Hi @JonathanDotCel , thank you for the detailed feedback! I recognize that if you're using WSL 1, moving to WSL 2 can be pretty challenging or frustrating. Currently our resources aren't on fixing this exact user scenario from a dev perspective but we have updated the docs to help make this distinction clearer ( https://github.com/MicrosoftDocs/WSL/commit/401070e92c7215dfc34db58c58a3c60167cb5616 ). Thank you for filing this!

JonathanDotCel commented 7 months ago

Challenging? No. The migration from WSL1 was the least of my issues. It worked first time from a WSL2 image to WSL1. The documentation and binary feedback is the problem.

mattwojo commented 7 months ago

@JonathanDotCel - I'm trying to wrap my head around what would be helpful to update in the docs.

I can't do anything about the in-product messages (like "Export in progress, this may take a few minutes.").
I added a note by the --vhd flag of the export command saying that this is only supported in WSL 2 (thanks for bringing that to my attention!)
I'm not sure that I understand this question or the use-case: "Is it possible for example to export a WSL2 image and import it as WSL1?" I believe the team is generally trying to encourage folks away from continuing to use WSL 1.. but if there's something here that you think would be helpful to have in the docs, I'd love help with trying to communicate it.
It sounds like this all stuff you already know, but the command wsl -l -v will list any Linux distros you've got installed and whether they are set to run on the WSL 1 or WSL 2 architecture. You can switch the architecture being used with wsl --set-version <distribution name> <versionNumber>. It's not really a matter of having "WSL 2 installed" as which architecture each distro that you've installed is set to run on. I see your suggestion to add a backup reminder when switching between WSL 1 and WSL 2 and am going to add that note in the doc, as well as a warning file loss and time if you have a lot of files and settings in the distro (I'm generally testing with a nearly empty distro, which is very quick to switch back and forth, so this is a good reminder).

Is there anything else that you feel that I should specifically add to the docs or call out as a warning?

Thanks again for filing this issue.

MicrosoftDocs / WSL