VS Code Integration

This guide covers setting up Visual Studio Code to work seamlessly with WSL2, allowing you to edit files in the WSL2 filesystem whilst running the VS Code interface on Windows.

1. Install VS Code on Windows

If you haven’t already installed VS Code:

  1. Download VS Code from https://code.visualstudio.com/

  2. Run the installer

  3. During installation, select:

    • Add "Open with Code" to Windows Explorer context menu

    • Add to PATH (recommended)

2. Install Remote - WSL extension

The Remote - WSL extension is essential for WSL2 development:

  1. Open VS Code

  2. Press Ctrl+Shift+X to open Extensions

  3. Search for "WSL"

  4. Install WSL by Microsoft (previously called "Remote - WSL")

The extension is now simply called "WSL" and is part of Microsoft’s Remote Development extension pack.

3. Connect to WSL2

3.1. Method 1: From Windows

  1. Open VS Code on Windows

  2. Press Ctrl+Shift+P to open Command Palette

  3. Type "WSL: Connect to WSL" and select it

  4. VS Code reconnects in WSL2 context

The status bar shows "WSL: Ubuntu" when connected.

3.2. Method 2: From WSL2 terminal (recommended)

Navigate to your project in WSL2 and open VS Code:

cd ~/dev/ems/admin-service
code .

This launches VS Code connected to WSL2 with the project folder open.

The first time you run code from WSL2, it automatically installs the VS Code Server component in your WSL2 environment.

4. Configure terminal

VS Code’s integrated terminal automatically uses Bash when connected to WSL2. No additional configuration is needed.

To verify, open the terminal (Ctrl+`) and check the shell:

echo $SHELL
# Should show: /bin/bash

5. Recommended extensions

Install these extensions whilst connected to WSL2 (they install in the WSL2 context):

5.1. Java development

  • Extension Pack for Java by Microsoft - Comprehensive Java support

  • Spring Boot Extension Pack by VMware - Spring Boot development tools

5.2. General development

  • GitLens - Enhanced Git integration

  • AsciiDoc - AsciiDoc syntax highlighting and preview

  • YAML - YAML language support

  • Docker - Docker integration

5.3. Install extensions from command line

Open the terminal in VS Code (connected to WSL2) and run:

# Java
code --install-extension vscjava.vscode-java-pack
code --install-extension vmware.vscode-boot-dev-pack

# General
code --install-extension eamodio.gitlens
code --install-extension asciidoctor.asciidoctor-vscode
code --install-extension redhat.vscode-yaml
code --install-extension ms-azuretools.vscode-docker

6. Settings for WSL2 development

6.1. User settings

Open settings (Ctrl+,) and configure:

{
  "files.eol": "\n",
  "files.autoSave": "afterDelay",
  "terminal.integrated.defaultProfile.linux": "bash",
  "git.autofetch": true,
  "editor.formatOnSave": true
}

6.2. Workspace settings

Create .vscode/settings.json in your project:

{
  "java.configuration.updateBuildConfiguration": "automatic",
  "java.compile.nullAnalysis.mode": "automatic",
  "maven.executable.path": "/usr/share/maven/bin/mvn",
  "spring-boot.ls.java.home": "/usr/lib/jvm/java-21-openjdk-amd64"
}

7. Working with files

7.1. Opening projects

Always open projects from their WSL2 location:

cd ~/dev/ems/admin-service
code .

Avoid opening projects from /mnt/c/. This forces VS Code to use the slow Windows filesystem for all operations.

7.2. File Explorer

When connected to WSL2, VS Code’s file explorer shows the Linux filesystem:

  • /home/<user>/ appears as the home directory

  • You can navigate to /mnt/c/ if needed, but avoid working there

7.3. Source control

VS Code automatically detects Git repositories and uses the Git installation from WSL2:

  • View changes in the Source Control panel (Ctrl+Shift+G)

  • Stage, commit, and push using the built-in Git integration

  • GitLens provides enhanced blame and history features

8. Running and debugging

8.1. Java applications

With the Java Extension Pack installed:

  1. Open a Java file

  2. Click the Run or Debug link above the main method

  3. Or use F5 to start debugging

The application runs inside WSL2 using the Linux JDK.

8.2. Spring Boot applications

With the Spring Boot Extension Pack:

  1. Open the Spring Boot Dashboard (in the sidebar)

  2. Click the play button next to your application

  3. Access the application at http://localhost:<port>;

WSL2’s localhostForwarding allows Windows browsers to access services running in WSL2.

9. Troubleshooting

9.1. VS Code not opening from terminal

If code . doesn’t work from WSL2:

# Check if VS Code is in PATH
which code

# If not found, add the Windows VS Code to PATH
echo 'export PATH="$PATH:/mnt/c/Users/<WindowsUser>/AppData/Local/Programs/Microsoft VS Code/bin"' >> ~/.bashrc
source ~/.bashrc

9.2. Extensions not loading

Some extensions need to be installed in the WSL2 context:

  1. Connect to WSL2 (Ctrl+Shift+P → "WSL: Connect to WSL")

  2. Go to Extensions (Ctrl+Shift+X)

  3. Look for extensions marked "Install in WSL: Ubuntu"

  4. Click to install them in WSL2

9.3. Slow file operations

If VS Code feels slow:

  1. Verify you’re working in the native WSL2 filesystem (~/dev/)

  2. Check that Windows Defender exclusions are configured (see Ubuntu Installation)

  3. Ensure you’re connected to WSL2 (check status bar)

10. Next steps

For Java development with full IDE features, see IntelliJ Integration.

Proceed to Workspace Setup to clone the EMS repositories and set up your development workspace.