WSL

When you use WSL2, Codex runs inside the Linux environment instead of using the native Windows sandbox. Choose WSL2 when you need Linux-native tooling, your repositories and developer workflow already live in WSL2, or neither native Windows sandbox mode works for your environment.

WSL1 was supported through Codex 0.114. Starting in Codex 0.115, the Linux sandbox moved to bubblewrap, so WSL1 is no longer supported.

Launch VS Code from inside WSL

For step-by-step instructions, see the official VS Code WSL tutorial.

Prerequisites

Windows with WSL installed. To install WSL, open PowerShell as an administrator, then run wsl --install (Ubuntu is a common choice).
VS Code with the WSL extension installed.

Open VS Code from a WSL terminal

# From your WSL shell
cd ~/code/your-project
code .

This opens a WSL remote window, installs the VS Code Server if needed, and ensures integrated terminals run in Linux.

Confirm you're connected to WSL

Look for the green status bar that shows WSL: <distro>.
Integrated terminals should display Linux paths (such as /home/...) instead of C:\.
You can verify with:
```
echo $WSL_DISTRO_NAME
```
This prints your distribution name.

If you don't see "WSL: ..." in the status bar, press Ctrl+Shift+P, pick WSL: Reopen Folder in WSL, and keep your repository under /home/... (not C:\) for best performance.

If the Windows app or project picker does not show your WSL repository, type \wsl$ into the file picker or Explorer, then navigate to your distro's home directory.

Use Codex CLI with WSL

Run these commands from an elevated PowerShell or Windows Terminal:

# Install default Linux distribution (like Ubuntu)
wsl --install

# Start a shell inside Windows Subsystem for Linux
wsl

Then run these commands from your WSL shell:

# Install and run Codex in WSL
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Work on code inside WSL

Working in Windows-mounted paths like /mnt/c/... can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like ~/code/my-app) for faster I/O and fewer symlink and permission issues:
```
mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repo
```
If you need Windows access to files, they're under \wsl$\Ubuntu\home<user> in Explorer.

Troubleshooting and FAQ

Large repositories feel slow in WSL

Make sure you're not working under /mnt/c. Move the repository to WSL (for example, ~/code/...).
Increase memory and CPU for WSL if needed; update WSL to the latest version:
```
wsl --update
wsl --shutdown
```

VS Code in WSL cannot find codex

Verify the binary exists and is on PATH inside WSL:

which codex || echo "codex not found"

If the binary isn't found, follow the Codex CLI setup instructions.

windows/wsl.md +99 −0 created

1# WSL

3When you use WSL2, Codex runs inside the Linux environment instead of using the

4native [Windows sandbox](https://learn.chatgpt.com/docs/windows/windows-sandbox). Choose WSL2 when you need Linux-native

5tooling, your repositories and developer workflow already live in WSL2, or

6neither native Windows sandbox mode works for your environment.

8WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux

9sandbox moved to `bubblewrap`, so WSL1 is no longer supported.

11## Launch VS Code from inside WSL

13For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).

15### Prerequisites

17- Windows with WSL installed. To install WSL, open PowerShell as an administrator, then run `wsl --install` (Ubuntu is a common choice).

18- VS Code with the [WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) installed.

20### Open VS Code from a WSL terminal

22```bash

23# From your WSL shell

24cd ~/code/your-project

25code .

26```

28This opens a WSL remote window, installs the VS Code Server if needed, and ensures integrated terminals run in Linux.

30### Confirm you're connected to WSL

32- Look for the green status bar that shows `WSL: <distro>`.

33- Integrated terminals should display Linux paths (such as `/home/...`) instead of `C:\`.

34- You can verify with:

36 ```bash

37 echo $WSL_DISTRO_NAME

38 ```

40 This prints your distribution name.

42If you don't see "WSL: ..." in the status bar, press `Ctrl+Shift+P`, pick

43 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not

44 `C:\`) for best performance.

46If the Windows app or project picker does not show your WSL repository, type

47 <code>\\wsl$</code> into the file picker or Explorer, then navigate to your

48 distro's home directory.

50## Use Codex CLI with WSL

52Run these commands from an elevated PowerShell or Windows Terminal:

54```powershell

55# Install default Linux distribution (like Ubuntu)

56wsl --install

58# Start a shell inside Windows Subsystem for Linux

59wsl

60```

62Then run these commands from your WSL shell:

64```bash

65# Install and run Codex in WSL

66curl -fsSL https://chatgpt.com/codex/install.sh | sh

67codex

68```

70## Work on code inside WSL

72- Working in Windows-mounted paths like <code>/mnt/c/...</code> can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like <code>~/code/my-app</code>) for faster I/O and fewer symlink and permission issues:

73 ```bash

74 mkdir -p ~/code && cd ~/code

75 git clone https://github.com/your/repo.git

76 cd repo

77 ```

78- If you need Windows access to files, they're under <code>\\wsl$\Ubuntu\home\<user></code> in Explorer.

80## Troubleshooting and FAQ

82Large repositories feel slow in WSL

84- Make sure you're not working under <code>/mnt/c</code>. Move the repository to WSL (for example, <code>~/code/...</code>).

85- Increase memory and CPU for WSL if needed; update WSL to the latest version:

86 ```powershell

87 wsl --update

88 wsl --shutdown

89 ```

91VS Code in WSL cannot find codex

93Verify the binary exists and is on `PATH` inside WSL:

95```bash

96which codex || echo "codex not found"

97```

99If the binary isn't found, follow the [Codex CLI setup instructions](#use-codex-cli-with-wsl).