WSL2 Development Environment Setup

This guide walks you through setting up a complete Java development environment using Windows Subsystem for Linux 2 (WSL2) on Windows 11. This setup provides near-native Linux performance for development tasks whilst maintaining the convenience of Windows as your primary operating system.

1. Why WSL2?

WSL2 offers significant advantages for Java development on Windows:

Benefit Description

Performance

Build times are 2-3x faster compared to native Windows due to Linux filesystem performance

Linux tooling

Native access to Linux command-line tools, shell scripts, and development utilities

IDE integration

Seamless integration with VS Code and IntelliJ IDEA running on Windows

Docker compatibility

Docker Desktop’s WSL2 backend provides excellent container performance

Claude Code

Claude Code works optimally in a Linux environment with proper shell support

2. Architecture overview

The recommended architecture places your projects in the WSL2 native filesystem whilst running Windows-based IDEs:

+----------------------------------------------------------+
|                      Windows 11                           |
|  +----------------------------------------------------+  |
|  |         IntelliJ IDEA / VS Code (Windows)          |  |
|  |                                                    |  |
|  |  Opens project from: \\wsl$\Ubuntu\home\...\       |  |
|  |  Uses JDK from: WSL2                               |  |
|  |  Uses Maven from: WSL2                             |  |
|  |  Runs/debugs in: WSL2                              |  |
|  +----------------------------------------------------+  |
|                          |                                |
|                          v                                |
|  +----------------------------------------------------+  |
|  |                     WSL2 Ubuntu                     |  |
|  |  ~/dev/ems/                                        |  |
|  |  +-- admin-service/       (Spring Boot)            |  |
|  |  +-- registration-portal/ (Angular)                |  |
|  |  +-- .m2/repository/      (Maven cache)            |  |
|  |                                                    |  |
|  |  JDK: /usr/lib/jvm/java-21-openjdk                 |  |
|  |  Maven: /usr/share/maven                           |  |
|  |  Claude Code: runs here                            |  |
|  +----------------------------------------------------+  |
+----------------------------------------------------------+

Keep projects in the WSL2 native filesystem (~/dev/) for optimal performance. Accessing files on /mnt/c/ is 10-50x slower due to the 9P protocol overhead.

3. Quick start checklist

Follow these guides in order:

  1. Windows Setup - Enable virtualisation and install WSL2

  2. Ubuntu Installation - Install and configure Ubuntu from the Microsoft Store

  3. Development Tools - Install OpenJDK, Maven, Git, and other essential tools

  4. Claude Code - Install and configure Claude Code for AI-assisted development

  5. VS Code Integration - Set up VS Code with the Remote-WSL extension

  6. IntelliJ Integration - Configure IntelliJ IDEA Community Edition for WSL2

  7. Workspace Setup - Clone repositories and configure your development workspace

4. Performance benchmarks

WSL2 significantly outperforms native Windows for I/O-intensive development tasks:

Operation Native Windows WSL2 (native FS)

git status

3-60 seconds

~50ms

npm install

5-10 minutes

~30 seconds

mvn compile

2-5 minutes

~20 seconds

Benchmarks based on typical project sizes. Your results may vary depending on project complexity and hardware specifications.

5. Next steps

Begin with Windows Setup to enable the required Windows features and install WSL2.

If you encounter issues during setup, refer to the Troubleshooting guide.