Codex CLI Install Troubleshooting: PATH, Sign-In, and WSL

If installation finishes but your shell reports codex: command not found, authentication is not the problem: the terminal cannot locate the executable. If Codex opens and then stalls during browser authentication, installation is already complete. Treat those as two separate failures.

Confirm the install in one command

Open a new terminal and run:

codex --version

A version number confirms that this shell can find and execute Codex. Skip to the sign-in section if authentication is the only remaining problem. If the command is missing, check whether you installed Codex in the same environment you are using now. A common mismatch is installing in PowerShell and then looking for the command in WSL, or the reverse.

Check which terminal ran the installer

On macOS, Linux, or WSL, run the official script inside that shell:

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

For native Windows, open PowerShell—not a WSL window—and run:

irm https://chatgpt.com/codex/install.ps1 | iex

If Node.js and npm are already installed, the npm package is another supported option:

npm install --global @openai/codex

After any method completes, close every terminal, open a fresh one, and run codex --version. Use one installation method. Multiple copies can leave an older executable earlier on PATH, making it unclear which version you are running.

The standalone installer places the executable in ~/.local/bin on macOS and Linux, and %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows.

If the file exists but the command does not, compare the install directory with PATH.

On macOS, Linux, or WSL:

ls -l ~/.local/bin/codex
printf '%s\n' "$PATH" | tr ':' '\n'

If ~/.local/bin is absent, run export PATH="$HOME/.local/bin:$PATH" in the current shell and test again. Once it works, add the same line to ~/.zshrc or ~/.bashrc.

In Windows PowerShell:

Test-Path "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin\codex.exe"
$env:Path -split ';'

If the executable exists but the directory is missing, add %LOCALAPPDATA%\Programs\OpenAI\Codex\bin to your Windows user Path, then reopen PowerShell.

Keep Windows and WSL installs separate

PowerShell and WSL are separate execution environments. By default, WSL appends Windows directories to $PATH, so it may be able to launch a Windows program such as codex.exe. That does not mean the Linux codex executable is installed in WSL. If you work inside WSL, install the Linux build there.

To set up WSL2, run this in an elevated PowerShell or Windows Terminal:

wsl --install

Restart Windows if prompted. Complete the initial Linux user setup, then enter WSL:

wsl

Inside the Linux shell, install Codex with the Linux script:

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

Open a new WSL shell and confirm with codex --version. Current Codex documentation targets WSL2; WSL1 has not been supported since Codex 0.115. Keeping projects under the WSL home directory, such as ~/code/..., instead of /mnt/c/... also avoids many filesystem and permission problems.

If you stay in PowerShell, keep only the Windows install. If you use WSL, keep installation, execution, and project files on the WSL side.

If browser sign-in never returns to the terminal

When Codex launches but authentication does not finish, restart the standard login flow:

codex login

After signing in to ChatGPT in the browser, the credentials should return to Codex. Check the current authentication state with:

codex login status

On a remote or headless machine—or a corporate network that blocks the local callback—the browser may complete authentication while the terminal keeps waiting. In that case, use the beta device-code flow. Personal accounts must first enable device-code authorization in ChatGPT security settings; managed workspaces require an administrator to allow it.

codex login --device-auth

To switch accounts or clear a suspect authentication cache, sign out and start again. codex logout removes the stored credentials, so use it only when you are ready to authenticate again.

codex logout
codex login

A managed ChatGPT workspace can restrict the allowed login method or workspace. If Codex keeps rejecting a personal account, check the organization’s policy before reinstalling.

If install and sign-in both look healthy

When the version and authentication status are correct but Codex still will not start, run the diagnostic summary:

codex doctor --summary

It checks the local installation, configuration, credentials, and execution environment. When requesting help, include the operating system, shell, output of codex --version, installation method, and the diagnostic item that failed. Never paste an access token or the contents of ~/.codex/auth.json.