Develop in Windows Subsystem for Linux (WSL)
Windows Subsystem for Linux (WSL) enables you to seamlessly run a Linux environment on Windows. The remote development functionality of Trae further extends this capability, enabling you to write, debug, and run code directly in your local WSL environment.
WSL remote development offers a development experience close to native Linux while retaining the ease of use of Windows. Whether building server applications, engaging in embedded development, or testing code in a Linux environment, WSL remote development provides an efficient and consistent experience without the need for virtual machines or dual-boot setups.
Architecture
The WSL development setup in Trae follows this architecture:
- Local PC: Runs Trae Client with UI Extensions
- WSL Distro: Runs Trae Server with Workspace Extension, AI Backend, Terminal, and Debugger
- File System Mapping: WSL file system is mapped to
/mnt/cfor seamless access
Limitations
Currently, only WSL 2 is supported, while WSL 1 is not supported.
Prerequisites
Before setting up WSL development in Trae, ensure you meet the following requirements:
- Your PC's operating system is Windows
- You know WSL well. If you are a beginner, it is recommended to read the official documentation to learn WSL before use
- You have installed WSL 2 on your PC. If you have not installed it, refer to the official documentation to complete installation
Connect to WSL
Follow these steps to connect Trae to your WSL environment:
Step 1: Open Remote Explorer
- Open the Remote Explorer and select the WSL Targets option at the top right
Step 2: Add a WSL Distro
- On the right of the WSL Targets text, click the + (Add a Distro) button
- The WSL distro selection panel appears
- Select the WSL distro you want to install. The currently available distros are:
- Ubuntu 20.04 LTS
- Ubuntu 22.04 LTS
- Ubuntu 24.04 LTS
Step 3: Install the Distro
- Trae starts installing the selected WSL distro. You can check the installation progress on the Terminal panel
Note: If the Terminal panel prompts you to create an account and a password, create them; otherwise, you only need to wait for the installation to complete.
Step 4: Connect to the Distro
- After the installation is complete, click the Refresh button on the right of the WSL Targets text
- The installed WSL distro appears in the list
- Hover the cursor over the WSL distro you want to connect and click the Connect in New Window or Connect in Current Window button, or you can right-click this WSL distro and select how to connect it in the shortcut menu
- Trae starts connecting to the specified WSL distro. Once connected, the name of this WSL distro appears at the bottom left
- Open a folder or clone a Git repository and start coding
Disconnect from WSL
You can disconnect from WSL in two ways:
- Exit Trae directly: The next time you open it, you will be prompted to complete the remote connection first
- Use menu: From the top menu bar, select File > Close Remote Connection
Quick Access Panel
You can open the quick access panel using shortcut Alt + Ctrl + O.
On the quick access panel, you can:
| Action | Description |
|---|---|
| 1 | Click to connect to the default WSL distro |
| 2 | Click to select a WSL distro to connect |
| 3 | Click to open the WSL operation panel on the left |
Additional Operations
Set a Default WSL Distro
Trae automatically sets the first installed WSL distro to "default distro". After installing other distros, you can right-click another WSL distro and select Set as Default Distro from the shortcut menu to set it as the default distro.
Manage Extensions
Extensions can run either on the local UI/server or within WSL. In the Installed list of the Extension Store, you can view the extensions installed both locally and in WSL, and manage them as needed.
Open a Terminal in WSL
From the top menu bar, select Terminal > New Terminal to open a terminal running in WSL, and then execute your commands.
Debugging in WSL
After connecting to WSL, you can use Trae's debugging features, which are similar to local debugging. You need to select the launch configuration in the launch.json file and press F5 to start debugging. The application will be launched on the remote host, and the debugger will be attached to it.