Windows and WSL projects#

Prepare a Linux workspace, connect it from Windows, and recover a changed WSL session without losing edits.

Choose the right project location#

A WSL project keeps source and Linux engine work in the selected distribution’s Linux filesystem. The Windows app supplies the window, editor and connection. A Windows-local project uses a different adapter; choose the host deliberately before editing.

Use an existing x86-64 Ubuntu 24.04 WSL2 distribution with a non-root default user. Keep the project under the Linux user’s directory, such as /home/your-user/projects/demo. /mnt/c and network shares do not satisfy this Linux workspace contract.

Check and connect#

Powershell
wsl --list --verbose

  1. Confirm that the intended distribution is listed as WSL version 2. The app’s project connection does not install a distribution.

  2. Select the Linux project from the Windows app using its WSL project path, for example \\wsl.localhost\Ubuntu-24.04\home\your-user\projects\demo.

  3. If the installed app offers backend preparation, review it and use the matching bundled backend. A manually substituted helper can be incompatible.

  4. Confirm the distribution, user, project root and connection status. Open and save one small text file before performing a transaction or running an engine.

Files, Git and engines#

Saved text, project settings and supported Source Control operations run through the Linux workspace. File writes check the saved revision. WSL-backed Git reads and edits use Linux Git for that project. A connected workspace does not enable every engine, binary viewer or remote Git transfer; check the action shown by your installed host.

Reconnect after changes#

Change or message

Recovery

WSL restarted

Preserve unsaved text, explicitly reconnect, and reread files before saving.

Project directory was moved or replaced

Reopen the intended directory; do not reuse an old connection for a new folder identity.

Root user, shared permissions or Windows mount rejected

Select a user-owned Linux folder with the intended non-root user.

Save outcome is uncertain

Reload and inspect the current saved content before repeating the write.

See Windows installation, Local workspaces and Diagnostics for package, backup and error-reporting steps.