From 163fa8bd34775167bc4176a2dd38f9c512090aaf Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 09:22:33 -0500 Subject: [PATCH 1/9] macos troubleshooting += installed to downloads --- docs/setup_vscode_macos.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/setup_vscode_macos.md b/docs/setup_vscode_macos.md index a287db7..fd18a65 100644 --- a/docs/setup_vscode_macos.md +++ b/docs/setup_vscode_macos.md @@ -607,6 +607,16 @@ Now, running the debugger will not display the assembly file. However, it will n +### Installed to Downloads +VSCode may think the system is read only if it is installed in the Downloads folder. + +Check if VS Code is installed in the Downloads folder. Remove it and try the [Install section](#install) again. +```console +$ ls ~/Downloads/ | grep "Visual Studio Code" +Visual Studio Code.app +$ rm -rf ~/Downloads/Visual\ Studio\ Code*.app ~/Downloads/VSCode-*.zip +``` + ## Acknowledgments Original document written by Andrew DeOrio awdeorio@umich.edu. From 0567ecfd46023d972f0f3e55e1ee152f2e475ccd Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 09:23:00 -0500 Subject: [PATCH 2/9] wsl troubleshooting += wsl --install stuck --- docs/setup_wsl.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index 3f873ea..61fa2f0 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -221,6 +221,9 @@ If these do not work, right click on the terminal window header. If you see opti This section is for common problems and solutions. +### `wsl --install` stuck +Cancel, [enable virtualization](#enable-virtualization), and `wsl --install` again. + ### Enable Virtualization WSL2 requires virtualization support. Follow the steps below to ensure it is enabled. From 85d084f7cd5c471f826475f87a34e9f988e7405b Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 09:34:20 -0500 Subject: [PATCH 3/9] WSL += nuclear option --- docs/setup_wsl.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index 61fa2f0..777ce77 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -253,6 +253,28 @@ Microsoft maintains an extensive [troubleshooting page](https://learn.microsoft. If you forgot you WSL password, follow the steps [here](https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password) to reset it. Scroll down to the part beginnning with "If you forgot the password for yoru Linux distribution:". +### Nuclear Option +If you've tried everything and want to delete your WSL install entirely. + +
+**WARNING:** This will delete all files inside WSL. +
+ +Start PowerShell an run it as administrator ([instructions](#install-wsl)). + +See what's installed. +```console +C:\WINDOWS\system32> wsl -l -v + NAME STATE VERSION +* Ubuntu-24.04 Running 2 +``` + +Delete. +```console +$ wsl --unregister ubuntu +$ wsl --unregister Ubuntu-24.04 # Your version might be different +``` + ## Acknowledgments Original document written by Andrew DeOrio awdeorio@umich.edu. From 3abf6601bfb036de78875dfdc39e3f5428dbe95d Mon Sep 17 00:00:00 2001 From: James Juett Date: Fri, 19 Dec 2025 14:05:12 -0500 Subject: [PATCH 4/9] typo --- docs/setup_wsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index 777ce77..e27f10b 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -260,7 +260,7 @@ If you've tried everything and want to delete your WSL install entirely. **WARNING:** This will delete all files inside WSL. -Start PowerShell an run it as administrator ([instructions](#install-wsl)). +Start PowerShell and run it as administrator ([instructions](#install-wsl)). See what's installed. ```console From 56692ffe63ea61c317de7ad89d9a58f0e9e32b39 Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 14:39:42 -0500 Subject: [PATCH 5/9] Control-C --- docs/setup_wsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index e27f10b..2db7a20 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -222,7 +222,7 @@ If these do not work, right click on the terminal window header. If you see opti This section is for common problems and solutions. ### `wsl --install` stuck -Cancel, [enable virtualization](#enable-virtualization), and `wsl --install` again. +Cancel by pressing ctrl + c, [enable virtualization](#enable-virtualization), and try `wsl --install` again. ### Enable Virtualization From 4744f7b12fbb5bf5950a1720762bdb5e7dc47aad Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 14:42:46 -0500 Subject: [PATCH 6/9] Correct `wsl --unregister` commands --- docs/setup_wsl.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index 2db7a20..6f78ff9 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -269,10 +269,9 @@ C:\WINDOWS\system32> wsl -l -v * Ubuntu-24.04 Running 2 ``` -Delete. +Delete each installation. Your version might be different and you might need to delete several. ```console -$ wsl --unregister ubuntu -$ wsl --unregister Ubuntu-24.04 # Your version might be different +$ wsl --unregister Ubuntu-24.04 ``` ## Acknowledgments From 974f58deaa11c1adb6bf0164421d773d5374b14e Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 14:44:11 -0500 Subject: [PATCH 7/9] Better title --- docs/setup_wsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index 6f78ff9..51bf620 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -253,7 +253,7 @@ Microsoft maintains an extensive [troubleshooting page](https://learn.microsoft. If you forgot you WSL password, follow the steps [here](https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password) to reset it. Scroll down to the part beginnning with "If you forgot the password for yoru Linux distribution:". -### Nuclear Option +### Delete and reinstall If you've tried everything and want to delete your WSL install entirely.
From 6a7738cf5592ad85cac59e7dcf5f433b8fa382a8 Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Fri, 19 Dec 2025 14:45:49 -0500 Subject: [PATCH 8/9] title improvement, include error text --- docs/setup_vscode_macos.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/setup_vscode_macos.md b/docs/setup_vscode_macos.md index fd18a65..ce95853 100644 --- a/docs/setup_vscode_macos.md +++ b/docs/setup_vscode_macos.md @@ -607,8 +607,10 @@ Now, running the debugger will not display the assembly file. However, it will n -### Installed to Downloads -VSCode may think the system is read only if it is installed in the Downloads folder. +### Read-only volume +VSCode may think the system is read only and **fail to update** if it is installed in the Downloads folder. For example: + +> Cannot update while running on a read-only volume. The application is on a read-only volume. Please move the application and try again. If you're on macOS Sierra or later, you'll need to move the application out of the Downloads directory. This might mean the application was put on quarantine by macOS. See this link for more information. Check if VS Code is installed in the Downloads folder. Remove it and try the [Install section](#install) again. ```console From 1bebad31075beca0eaacb0e09750e784e5e24b2e Mon Sep 17 00:00:00 2001 From: Andrew DeOrio Date: Mon, 22 Dec 2025 11:23:55 -0500 Subject: [PATCH 9/9] Replace Ctrl-C with "close powershell" --- docs/setup_wsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup_wsl.md b/docs/setup_wsl.md index 51bf620..8955129 100644 --- a/docs/setup_wsl.md +++ b/docs/setup_wsl.md @@ -222,7 +222,7 @@ If these do not work, right click on the terminal window header. If you see opti This section is for common problems and solutions. ### `wsl --install` stuck -Cancel by pressing ctrl + c, [enable virtualization](#enable-virtualization), and try `wsl --install` again. +Cancel by closing PowerShell, [enable virtualization](#enable-virtualization), and try `wsl --install` again. ### Enable Virtualization