The Codex desktop app fails to start and shows one of these:
Unable to locate the Codex CLI binary. Set CODEX_CLI_PATH or ensure the
Electron resources include bin/codex.
Unable to locate the Codex CLI binary. Set the CODEX_CLI_PATH environment
variable to the full path of the Codex CLI binary, or ensure the Electron
resources include the binary at bin/codex.
Both are the same failure with different wording across app versions. This guide fixes it, starting with the trigger that accounts for most reports.
Why This Happens
The Codex desktop app does not contain the agent. It is an Electron shell that launches the Codex CLI as a child process. At startup it resolves the CLI in this order:
- The path in the
CODEX_CLI_PATHenvironment variable, if set. bin/codexinside the app's own bundled resources.
If neither resolves to a file it can execute, the app aborts with this message. Four situations break that resolution:
| Trigger | What breaks |
|---|---|
| Agent Environment switched to WSL | The app looks for a Linux codex binary that is not present in the Windows package |
| Microsoft Store install redirected to a non-C: drive | The app cannot resolve the path to its own bundled resources |
CODEX_CLI_PATH set to a stale path | The variable wins the lookup and points at a file that no longer exists |
| Partial or interrupted CLI install | The CLI binary genuinely is not on disk |
Fix 1: Switch Agent Environment Back to Windows
If the error appeared immediately after you changed Settings → Agent Environment from Windows to Windows Subsystem for Linux, that is the cause. The app cannot currently launch a WSL-installed CLI reliably, and the Windows package ships only codex.exe.
- Open the Codex app settings (if the app will not open far enough, continue to Fix 2).
- Set Agent Environment back to Windows.
- Fully quit the app — check the system tray — and relaunch.
Users who reverted this setting report the app starting normally again.
Fix 2: Set CODEX_CLI_PATH Explicitly
If you have a working CLI, point the app straight at it.
First confirm the CLI actually runs and find its real location:
codex --version
where.exe codex
A typical npm global install resolves to something like C:\Users\you\AppData\Roaming\npm\codex.cmd, with the executable alongside it.
Set the variable persistently:
setx CODEX_CLI_PATH "C:\Users\you\AppData\Roaming\npm\node_modules\@openai\codex\bin\codex.exe"
On macOS or Linux:
which codex
echo 'export CODEX_CLI_PATH="/opt/homebrew/bin/codex"' >> ~/.zshrc
source ~/.zshrc
Two things to watch:
setxonly affects processes started after it runs. Close the app completely and reopen it — a restart of the shell alone is not enough if the app was already running.- If
CODEX_CLI_PATHis already set to something wrong, it takes priority over the app's bundled binary, so a stale value causes the error even on an otherwise healthy install. Clear it withsetx CODEX_CLI_PATH ""(orunset CODEX_CLI_PATH) and restart before assuming anything else is broken.
Fix 3: Reinstall the App to the Default Drive
If you changed the Windows setting that sends new Microsoft Store apps to a different drive (for example E:), the app can fail to locate its own resources.
- Uninstall Codex.
- Open Settings → System → Storage → Advanced storage settings → Where new content is saved and set new apps to save to
C:. - Reinstall Codex.
- Launch it before changing any other settings.
This has been confirmed to resolve the error immediately for non-default-drive installs.
Fix 4: Reinstall the CLI Itself
If codex --version fails in a terminal, the app is right — there is no CLI to find.
If the reinstall itself fails with Could not find Codex package or platform npm release assets for Codex, that is a separate installer fault — see how to work around it.
npm install -g @openai/codex
codex --version
Watch for this during first run:
Missing optional dependency @openai/codex-linux-x64. Reinstall Codex: npm install -g @openai/codex
Codex CLI ships its native binary as a per-platform optional dependency. If your network, a proxy, or an --omit=optional flag prevented that download, the loader script installs but has nothing to execute. Re-run the install without restrictions.
If the install fails with EACCES instead, fix the permission problem first — see npm EACCES permission denied installing Codex.
Fix 5: Use the CLI Directly
The desktop app is optional. Everything the app does is available from the terminal:
codex
If you are blocked and need to work, run the CLI and revisit the app later. On Windows the CLI runs equally well inside WSL, which sidesteps the app's WSL launcher entirely.
Verify the Fix
Work through these in order — the first one that fails tells you which layer is broken:
# 1. Does the CLI exist and run?
codex --version
# 2. Where does the OS resolve it?
where.exe codex
# 3. Is CODEX_CLI_PATH set, and does it point at a real file?
echo $env:CODEX_CLI_PATH
Test-Path $env:CODEX_CLI_PATH
# 4. If you are targeting WSL, does the CLI answer there?
wsl --exec /usr/local/bin/codex --version
Then relaunch the desktop app from a fresh start — not from a minimized tray instance.
Prevent It Coming Back
- Leave Agent Environment on Windows unless you have verified the WSL path works on your build.
- Install Microsoft Store apps to the default drive.
- If you set
CODEX_CLI_PATH, revisit it after every CLI upgrade or Node version change; a version-pinned path goes stale. - Keep the CLI and the desktop app updated together rather than one at a time.