Cursor + WSL (Linux-first) Setup

cursor-wsl.md

Cursor + WSL (Linux-first) Setup

This setup ensures Cursor, Bun, Node, Git, and AI agents run in a real Linux filesystem for speed, stability, and correct tooling.

1. Install WSL + Ubuntu

wsl --install

Restart Windows, open Ubuntu, then:

sudo apt update && sudo apt upgrade -y

2. Install Cursor on Windows

Download and install Cursor normally on Windows. Inside Cursor, install the WSL extension.

3. Force Cursor to use WSL and start in Linux home

Open Cursor → Settings (JSON) and set:

{
  "terminal.integrated.defaultProfile.windows": "WSL (Ubuntu)",
  "terminal.integrated.profiles.windows": {
    "WSL (Ubuntu)": {
      "path": "C:\\Windows\\System32\\wsl.exe",
      "args": ["-d", "Ubuntu", "--cd", "/home/<your-user>/code"]
    }
  },
  "terminal.external.windowsExec": "C:\\Windows\\System32\\wsl.exe"
}

Replace <your-user> with your Linux username. Do not set terminal.integrated.cwd. WSL handles the working directory.

Restart Cursor.

4. Create Linux workspace

Inside WSL:

mkdir -p ~/code

5. Open projects correctly

From WSL:

cd ~/code/my-project
cursor .

6. Verify

In Cursor terminal:

pwd
uname -a
which node

Expected:

• pwd → /home/.../code
• uname → Linux
• which node → not C:\Program Files

7. Access Linux files from Windows Explorer (optional)

\\wsl$\Ubuntu\home\<your-user>\code

8. If you already have code in Windows and want to move it

From WSL:

rsync -av --progress /mnt/c/Users/<WindowsUser>/Code/ ~/code/

This preserves git repos, symlinks, timestamps, and large node_modules correctly.

Why this matters

/mnt/c is slow and breaks file watchers, native modules, and AI indexing. /home is real Linux and is required for Bun, Node, Cursor AI, and monorepos to work correctly.