AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Installing Codex CLI in WSL (Ubuntu) — the trap where the Windows codex wins, measured up to the login step

One line summary

On our PC, which already had Codex CLI installed on Windows, WSL Ubuntu resolved codex to the Windows copy, and codex --version ended with a Missing optional dependency @openai/codex-linux-x64 error. Installing separately inside WSL and putting that path first on PATH gave the correct result.

Who this is for

• Anyone using codex on Windows via npm install -g @openai/codex who now wants it in WSL too
• Anyone who types codex in WSL and gets an error out of a codex.js under /mnt/c/...

Test environment

Commands inside WSL were run from Windows as wsl.exe -d Ubuntu -- bash -lc '...'. The code blocks below shorten that to wsl.

1. Check the distro and node first

wsl -l -v
wsl -d Ubuntu -- bash -lc 'cat /etc/os-release; uname -r'
wsl -d Ubuntu -- bash -lc 'command -v node; node --version; command -v npm; npm --version'

The Ubuntu on this PC already had node v22.22.1 and npm 9.2.0 in /usr/bin, so we skipped the node setup step. On a distro without node you would have to get node in place here, and we did not run through that (see "What we did not test" below).

2. Before installing, see where codex resolves

This is the heart of the note.

wsl -d Ubuntu -- bash -lc 'which -a codex'

/mnt/c/Users/User/AppData/Roaming/npm/codex

Printing this PC's WSL PATH showed 27 entries starting with /mnt/c, and /mnt/c/Users/User/AppData/Roaming/npm (the Windows global npm folder) was among them. That's why which finds a Windows file even though codex was never installed inside WSL.

That file is an sh script npm generated, so WSL can indeed run it. But running this install from WSL ended with an error about a missing Linux optional dependency.

Error: Missing optional dependency @openai/codex-linux-x64. Reinstall Codex: npm install -g @openai/codex@latest
    at findCodexExecutable (file:///mnt/c/Users/User/AppData/Roaming/npm/node_modules/@openai/codex/bin/codex.js:107:9)

The exit code was 1. The error suggests reinstalling with npm install -g. We did not try reinstalling on the Windows side; we solved it instead by installing a Linux copy inside WSL.

3. Install inside WSL

To keep the PC untouched, this round installed into a temp folder under the home directory.

wsl -d Ubuntu -- bash -lc 'mkdir -p ~/longtail_tmp/prefix && cd ~/longtail_tmp && npm install --prefix ~/longtail_tmp/prefix @openai/codex@latest'

added 2 packages in 7s

The two packages installed were codex and codex-linux-x64. The codex-linux-x64 package came along with the WSL temp install.

prefix@ /home/<user>/longtail_tmp/prefix
└── @openai/codex@0.154.0

If you actually mean to keep using it, npm install -g @openai/codex is the usual route. This PC's WSL global npm folder, per npm config get prefix, was /home/<user>/.npm-global, under the user's home. We did not run the global install this round.

4. Fix the PATH order and check the version

wsl -d Ubuntu -- bash -lc 'PATH="$HOME/longtail_tmp/prefix/node_modules/.bin:$PATH"; which -a codex; codex --version < /dev/null'

/home/<user>/longtail_tmp/prefix/node_modules/.bin/codex
/mnt/c/Users/User/AppData/Roaming/npm/codex
codex-cli 0.154.0

which -a now lists two. The WSL install at the top is the one that ran, and the version came back as the 0.154.0 we put in WSL. Switching to a global install only moves the same question around — which folder comes first on PATH — so after installing, checking the order with which -a codex is the safe move (we did not run the global-install case).

5. Up to, but not including, login

wsl -d Ubuntu -- bash -lc '~/longtail_tmp/prefix/node_modules/.bin/codex login status < /dev/null'

Not logged in

The exit code was 1. The freshly installed codex in WSL reported Not logged in. How to check login state is written up separately in Checking Codex CLI login status. We did not run codex login in this note.

Results

What failed

• codex --version before installing failed as shown above. That is the symptom this note is about.
• Our first attempt passed export PATH=$HOME/...:$PATH without quotes and produced a stream of export: ... not a valid identifier errors, because the Windows PATH mixes in paths with spaces such as Program Files. We re-ran it wrapped in double quotes, as PATH="$HOME/...:$PATH".
• After running codex --version from the WSL install, we found a ~/.codex/tmp/arg0/ folder in the WSL home. The creation time on ~/.codex was recorded as 17:24:57, in the same window as that first run. We deleted the temp install folder ~/longtail_tmp and left ~/.codex in place.

What we did not test

• We did not run through getting node in place (apt, nvm and so on) on a distro without it. This PC already had node.
• We did not run a WSL global install with npm install -g.
• We did not run codex login or any prompt after logging in. We also did not check how browser login opens from WSL.
• We did not try the /etc/wsl.conf setting that turns off appending the Windows PATH. This PC's wsl.conf had only [user] and [boot] sections.
• We did not check distros other than Ubuntu 26.04, or WSL1.

Related notes

• Installing Codex CLI on Windows
• Checking Codex CLI login status
• Checking and updating the Codex CLI version