Codex won't download or install

The download stalls, the installer fails, or npm finishes and codex still isn't there. The causes in order of frequency, starting with the wrong npm package name.

Last reviewed 2026-08-04 · verified against the pingdotgg/t3code repo

Three different failures get described the same way. Identify which one you have first — they have nothing in common.

1. The install succeeded but codex isn't there#

Check the package name first#

This is the most common Codex install failure by a wide margin:

npm i -g @openai/codex     # correct
npm i -g codex             # WRONG

The unscoped codex package is an unrelated project from 2012 with no connection to OpenAI. It installs successfully, which is what makes this so confusing — you get a codex command that behaves nothing like the documentation.

Check what you actually have:

npm ls -g --depth=0 | grep -i codex

If you see plain codex@ rather than @openai/codex@, remove it and install the right one:

npm uninstall -g codex
npm i -g @openai/codex
codex --version

Otherwise it's PATH#

The install worked, the binary exists, your shell can't see it. Very common with nvm, Volta, mise, or a custom npm prefix:

npm ls -g --depth=0        # is it installed?
npm bin -g                 # where did it go?
which codex                # macOS / Linux

where.exe codex            # Windows

If npm bin -g prints a directory that isn't on your PATH, that's your answer. On Windows, you also need to sign out and back in after a global install — applications inherit the environment from login time.

Full PATH walkthrough →

npm permission errors#

If the install printed EACCES or permission errors and you didn't notice, it may have half-failed. Don't reach for sudo — move the prefix somewhere you own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
npm i -g @openai/codex

sudo npm i -g appears to work and leaves root-owned files that break the next install in a more confusing way.

2. The download itself fails#

Try the official install script instead of npm#

It fetches a prebuilt binary and sidesteps npm entirely:

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

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Corporate networks and proxies#

If you're behind a proxy, npm needs to know about it in its own config — it doesn't inherit your shell environment reliably:

npm config get registry
npm config get proxy
npm config get https-proxy

Standalone installers download from releases.openai.com, and binaries come from GitHub. If your network filters either, the install script fails while npm might still work, or the reverse. Knowing which host is blocked tells you which route to take.

Just download the binary manually#

The most reliable fallback when automated installs fail — no npm, no install script, no dependency resolution:

Windows x64    codex-x86_64-pc-windows-msvc.exe
macOS ARM      codex-aarch64-apple-darwin.tar.gz
Linux x64      codex-x86_64-unknown-linux-musl.tar.gz

Direct download links and architecture detection →

Partial or corrupt downloads#

If a download completed but the binary misbehaves, verify it rather than guessing. Linux musl builds ship .sigstore bundles:

cosign verify-blob \
  --bundle codex-x86_64-unknown-linux-musl.sigstore \
  codex-x86_64-unknown-linux-musl.tar.gz

3. It installed but won't run#

At this point it isn't a download problem, and the fix is elsewhere:

The Codex browser extension#

codex extension download is a slightly different problem. The extension is installed through your browser's store, but it talks to the desktop app through a native messaging manifest — and when that manifest is stale or incomplete after an update, the extension appears installed but refuses to start, reporting a missing required path.

That's a known open bug rather than a download failure: manifest entry is missing →

Verify before moving on#

codex --version    # binary resolves
codex login        # authentication works
codex              # a session actually starts

All three must pass before you connect an editor extension or a GUI like T3 Code. Those launch Codex as a subprocess, so a half-working install shows up there as an unrelated-looking error and you'll debug the wrong layer.

FAQ#

Why isn't Codex downloading?#

Most often the download isn't the problem — the install completed but installed the wrong package, or the binary isn't on your PATH. If the transfer genuinely fails, try OpenAI's install script instead of npm, or download the binary directly from GitHub releases.

Why doesn't the codex command work after installing?#

Check that you installed @openai/codex and not the unscoped codex, which is an unrelated 2012 project. Run npm ls -g --depth=0 | grep -i codex to see which one you have.

How do I install Codex behind a corporate proxy?#

Set the proxy in npm's own configuration rather than only in your shell environment, since npm doesn't reliably inherit it. If the registry is reachable but releases.openai.com isn't, use npm; if the reverse, use the install script or a direct binary download.

The Codex installer runs but nothing happens — what now?#

Verify with codex --version. If that fails, the install didn't complete; if it succeeds but a GUI can't find Codex, it's a PATH inheritance problem rather than an install problem.

Can I install Codex without npm?#

Yes. Use OpenAI's install script, or download the prebuilt binary for your platform from GitHub releases. Neither needs Node.js.