Codex update failed: five causes to check
Identify the executable and installation method, update that installation, then verify the path and version again.
Error message
A Windows self-update report includes this exact final line:
Error: `powershell -ExecutionPolicy Bypass -c '$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex'` failed with status exit code: 1
The same report first prints Could not download or verify ...; retrying from GitHub Releases. That line describes a download fallback; the subsequent command failure is the actionable error. A second report was closed as a duplicate. The underlying issue remained open when reviewed. Do not treat the warning by itself as proof that the update failed.
A separate Windows desktop runtime report records this sequence as one attempted workaround revealed missing companion binaries:
Unable to locate the Codex CLI binary or required runtime components.
Windows cannot find file 'codex-windows-sandbox-setup.exe'
failed to spawn code-mode host
When it happens
This guide covers CLI installations on Windows, macOS and Linux, plus reported Windows desktop cases. It does not assume the desktop app, a terminal CLI and an IDE extension all use the same executable. First distinguish an installer failure from an update that completed but left another executable earlier on your shell’s path. The official README documents standalone, npm, Homebrew and manual release installs. The command and repair must match the installation you actually use.
On Windows, issue #46684 describes codex update spawning Windows PowerShell 5.1 even though the caller used PowerShell 7. In that reported environment Get-FileHash was unavailable to the spawned process. This is a specific environment failure, not evidence that every Windows update has a broken checksum. Separate desktop reports describe a stale CODEX_CLI_PATH override or missing companion binaries after an app update; those are different branches from an npm or standalone installer failure.
Match the error to the right check
The lines below are copied from the linked reports or vendor documentation. They are examples of observed output, not messages every Codex updater necessarily emits. Match the complete failing command and client before following a branch; a warning followed by a successful fallback is not itself a failed update.
| Error text seen in a report or tool | Start with |
|---|---|
Could not download or verify | Network interruption and proxy or registry |
failed with status exit code: 1 | Network interruption, then inspect the final installer error |
Get-FileHash | Version or runtime mismatch: Windows PowerShell 5.1 case |
npm error code EACCES | Permissions or sandbox |
EPERM: operation not permitted, unlink | Permissions or sandbox: an in-use Windows binary may be involved |
npm warn EBADENGINE Unsupported engine | Version or runtime mismatch: check whether you installed the unrelated codex package |
npm ERR! Error: ENOSPC, write | Disk space |
Unable to locate the Codex CLI binary or required runtime components. | Version or runtime mismatch: desktop runtime and companion files |
The ENOSPC line comes from npm’s generic error reference, not from a reproduced Codex-specific update. The EBADENGINE line was observed in a report about the wrong npm package, not as a general requirement of @openai/codex. Likewise, the proxy case below is a reported desktop-app experience; it is not a confirmed universal cause of failed CLI updates.
Fixes by cause
Network interruption
Symptoms. A standalone installer cannot retrieve its release metadata or asset, pauses, then prints Could not download or verify before trying GitHub Releases. If the second source succeeds and codex --version changes, the update succeeded despite the first warning. If both fail, retain the final error and the host named in it; a DNS failure, timeout, HTTP response and checksum failure imply different next checks. In the Windows report, the final blocker was Get-FileHash, not simply the first download warning.
Decide. First confirm which installation you are updating. In PowerShell, inspect Get-Command codex -All; on macOS or Linux, use command -v codex. For a standalone install, check reachability of the two documented distribution endpoints without downloading or executing a script:
curl.exe -I https://releases.openai.com/codex/
curl.exe -I https://github.com/openai/codex/releases
curl -I https://releases.openai.com/codex/
curl -I https://github.com/openai/codex/releases
An HTTP response proves only that the host was reached; a 403/404 on a directory URL does not by itself mean the actual release asset is unavailable. If the connection fails, check the network, VPN and DNS path for that host before retrying. Do not turn off checksum verification to force an install.
Repair. Once reachability has returned, use the installer for the same environment. The official README documents the normal commands and a GitHub Releases fallback override. In PowerShell, the explicit fallback is:
$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex
On macOS or Linux:
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh
These commands execute an official remote installer. Read the linked README and installer source before running them in your environment. If npm was the original installation method, retry npm install -g @openai/codex instead; do not install a second standalone copy just because npm’s registry was temporarily unreachable.
Verify. Open a new shell, resolve the path again, then run codex --version. Compare the version with the one recorded before the attempt. Test the same client that failed; a desktop app update is not validated by an unrelated global CLI version.
Permissions or sandbox
Symptoms. During npm installation, a WSL report shows npm error code EACCES while writing under /usr/lib/node_modules/@openai/codex. A Windows report describes an in-use codex.exe blocking replacement. Those are different conditions: the first concerns ownership of the npm global prefix, while the second may involve a file handle. A Codex sandbox can also intentionally block writes outside its allowed roots; that does not mean the package is broken.
Decide. In the shell where the install failed, inspect the target before changing permissions:
npm prefix -g
command -v codex
npm prefix -g
Get-Command codex -All | Select-Object CommandType, Source
Check whether the global prefix is writable by your normal account and whether a Codex app or CLI process still has the executable open. In a managed Codex task, compare the prefix with the sandbox’s allowed write roots; run the user-level installer in a normal terminal when the prefix is outside the task sandbox. Do not disable the sandbox just to make an installer write to a protected system directory.
Repair. Exit active Codex sessions before replacing an in-use binary. For npm EACCES, follow npm’s user-owned Node installation guidance rather than recursively changing ownership of system package directories. After selecting a writable npm installation owned by your user, retry the official scoped package command:
npm install -g @openai/codex
That same npm command is valid in PowerShell. If your organization manages the global prefix, ask its administrator to repair permissions; sudo npm install -g can create another ownership problem and does not solve a Codex sandbox policy.
Verify. Check npm prefix -g and the resolved executable path in the same shell, then run codex --version. If npm says the update completed but warns about EPERM cleanup, compare the actual version before assuming failure; one report documents a successful update with leftover temporary files.
Version or runtime mismatch
Symptoms. The update command finishes, yet a shell still reports an old Codex version; or the desktop app says it cannot locate its CLI or companion runtime. Sometimes a user accidentally installs the unrelated unscoped npm package codex, whose old dependency chain can produce npm warn EBADENGINE Unsupported engine (report). The proper package is @openai/codex. A reported Windows self-update produced a Get-FileHash failure because the spawned Windows PowerShell 5.1 process lacked that cmdlet; running the parent command from PowerShell 7 alone did not change the child process (issue #46684).
Decide. Compare the path and package target before reinstalling anything:
Get-Command codex -All | Select-Object CommandType, Source
npm ls -g @openai/codex --depth=0
node --version
codex --version
powershell -NoProfile -Command "Get-Command Get-FileHash"
command -v codex
npm ls -g @openai/codex --depth=0
node --version
codex --version
Run only the block for your OS. npm ls applies to an npm installation; it will not identify a separately bundled desktop backend or a manually downloaded binary. If Get-FileHash is missing only in Windows PowerShell 5.1, keep the installer tail and inspect that shell’s module loading rather than disabling checksum checks. If the app reports missing companion files, do not copy a single codex.exe between app versions; a Windows report shows why that can expose further missing binaries.
Repair. For an npm install that points at the wrong scoped package or an outdated global copy, update the documented package in the Node environment used by that shell:
npm install -g @openai/codex
For a Homebrew cask, use brew upgrade --cask codex. For the standalone installer, rerun its official command from the README after fixing the failed prerequisite. Do not apply all three update mechanisms to one path. A desktop backend mismatch requires the desktop app’s own update or a supported repair path, not proof by npm ls alone.
Verify. In a fresh shell, run the path and version checks again. Launch the affected desktop app separately if that was the failing client. If login now fails with refresh_token_invalidated, use the login guide; an authentication symptom is not an installation version check.
Disk space
Symptoms. npm documents the exact generic line npm ERR! Error: ENOSPC, write. It means the installer could not write to a required filesystem; the npm documentation notes that space or write permission may be involved. This is a diagnostic branch, not a claim that a Codex-specific release has a disk-space regression. A nearly full download/cache volume and an adequately sized installation volume can coexist.
Decide. Check the actual installation and temporary volumes. In PowerShell:
npm prefix -g
npm config get cache
Get-Volume | Select-Object DriveLetter, SizeRemaining, Size
On macOS or Linux:
npm prefix -g
npm config get cache
df -h .
The Windows volume command is from Microsoft’s reference; df is the standard filesystem-space inspection described in the GNU manual. Check the volume containing the returned prefix and npm cache, not only the current working directory. On a managed workstation, quotas can also reject writes before a drive appears physically full.
Repair. Free space in the relevant user-controlled location through your OS storage tools, or ask an administrator to adjust a quota. Do not delete Codex sessions, configuration, npm caches, release files or arbitrary directories blindly; first back up anything you plan to remove. When free space and write permission have been restored, retry the original documented command:
npm install -g @openai/codex
This retry is appropriate only if npm was your install method. A standalone or desktop update should be retried with its own updater after the volume issue is resolved.
Verify. Check available space again, confirm the installer exits successfully, and compare the resolved executable path and codex --version in a new shell. If ENOSPC persists while space is available, investigate quota and permissions instead of deleting more data.
Proxy or mirror
Symptoms. The browser reaches websites while npm uses an unavailable custom registry, or a standalone updater reaches its primary host but not the fallback. A macOS desktop report describes an app repeatedly downloading the same update; one commenter said disabling a local proxy helped them. That is an individual report, not proof that every update loop is proxy-related. A configured npm mirror can also serve stale or unavailable package metadata independently of the Codex release service.
Decide. For npm, compare the configured registry with the public one and test the explicit public endpoint without changing permanent settings:
npm config get registry
npm ping --registry=https://registry.npmjs.org/
For PowerShell, inspect proxy variable names and addresses only; never paste credentials embedded in a proxy URL into a support ticket:
Get-ChildItem Env:*PROXY* | Select-Object Name, Value
For macOS/Linux shells:
env | grep -i proxy
The npm registry documentation explains why a custom registry can be selected, while npm ping tests the selected endpoint. A successful ping does not prove that every platform-specific Codex package asset is available. For a standalone updater, inspect the documented releases.openai.com and GitHub paths in the network branch instead.
Repair. If the custom npm mirror is the failing path and your policy permits the public registry, choose it for this one update without permanently rewriting .npmrc:
npm install -g @openai/codex --registry=https://registry.npmjs.org/
If an authenticated corporate proxy is mandatory, ask its owner to fix connectivity; do not publish proxy URLs containing usernames or passwords. For the standalone installer, the official GitHub Releases override in the network branch is a supported alternative when its primary release host is unreachable. For a desktop app update loop, use the app’s supported update flow after correcting an identified proxy; a CLI reinstall is a different product path.
Verify. Run npm ping --registry=https://registry.npmjs.org/ again if npm was affected, then resolve codex and check its version. For the desktop app, verify its own About/version screen and whether the repeated update prompt has stopped. If it still loops, keep the app version, proxy state, timestamp and updater log for Support rather than repeating installations without new evidence.
Fix it step by step
- Save work and record the failing path. Completely exit active Codex CLI sessions, the IDE extension and the desktop app before replacing an executable. Windows reports of
EPERMoncodex.exesuggest an in-use binary can block cleanup; exiting is a precaution inferred from those reports, not a confirmed universal fix. Keep the full error and old version. Before any Windows desktop cleanup, back up%USERPROFILE%\.codex, includingsessions,archived_sessions, SQLite databases with their-waland-shmfiles, andsession_index.jsonl(reported data-safety lesson). Do not remove that directory to test an update. - Identify the executable the affected shell resolves. In PowerShell run
Get-Command codex -All | Select-Object CommandType, Source; on macOS/Linux runcommand -v codex. Then runcodex --version. These are diagnostic shell commands, not installer commands. If there are multiple entries, note the first path. For npm, compare it withnpm prefix -gin the same Node environment. A version displayed by a CLI does not establish the build used by a separately bundled desktop backend. - Update the installation you identified. For npm, use the documented Codex package command
npm install -g @openai/codex, in that same Node environment. For a Homebrew cask, usebrew upgrade --cask codex. For the standalone installation, rerun the official installer: macOS/Linuxcurl -fsSL https://chatgpt.com/codex/install.sh | sh; Windowspowershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". If you manually downloaded a binary, use the matching architecture from official releases and retain the prior copy until the new one launches. Do not apply all of these methods to one environment. - Read the real end of a standalone update failure. The installer normally tries
releases.openai.com, then GitHub Releases if that download fails; the README documentsCODEX_INSTALLER_USE_RELEASES_OPENAI_COM=falseto choose GitHub Releases deliberately. If the final failure isGet-FileHash, confirm which PowerShell executable ran and whether the cmdlet is available there. In the open Windows issue, starting from PowerShell 7 did not fix a broken Windows PowerShell 5.1 environment. Do not bypass hash verification, download from an unofficial mirror or claim that the fallback warning is a fix. - If the desktop app appears stale, inspect overrides before moving binaries. Check the user and process values of
CODEX_CLI_PATHand compare them with the app’s actual bundled or managed runtime. Issue #46155 reports a stale%USERPROFILE%\.codex\.sandbox-bin\codex.exeoverride, no visible window and CPU use after auto-update. Issue #47759 reportsUnable to locate the Codex CLI binary or required runtime components, thenWindows cannot find file 'codex-windows-sandbox-setup.exe', thenfailed to spawn code-mode host ... (os error 2)as one attempted workaround revealed missing sibling files. If you evaluate that community workaround, compare SHA-256 hashes and keepcodex.exewith companion binaries from the same runtime version. It is not an official repair; do not paste binaries from unrelated installations or delete user history. - Verify the intended client separately. Open a fresh terminal, resolve the path again and run
codex --version. Then launch the affected CLI, desktop app or extension and check the original operation. Ifcodex login statussays logged in but a request returnsrefresh_token_invalidated, follow the login troubleshooting guide; issue #46155 reports that combination. An authentication failure does not prove that an update command failed.
Still not working?
- If npm reports
EACCES, follow npm’s global-install permission guidance for that platform. Its user-owned directory example is not a Windows procedure; avoid a reflexivesudoreinstall that creates yet another executable. - If the resolved version is unchanged, compare the executable path, npm prefix, shell and app backend. Record which installation actually received the update before reinstalling anything.
- If a Windows desktop update still fails, preserve the exact installer tail, app build, runtime path and relevant log lines. The linked issues are individual reports, not a guaranteed fix or a named fixed release.
Related errors
- Codex command not found when no CLI executable resolves.
- Codex login failed when the updated client opens but a session refresh fails.
- Codex Windows sandbox setup when the app opens but local command setup fails.
- Codex config location when CLI and app appear to read different homes.
FAQ
How do I update Codex CLI?
Identify whether your CLI was installed through npm, Homebrew, the standalone installer or a manual release. Use the matching command in step 3, then resolve the executable path and version again. Updating another installation does not change the CLI your shell actually launches.
Why does codex —version still show the old version after updating?
The shell may resolve another codex executable, or the desktop app may use a separate bundled runtime. Compare Get-Command codex -All or command -v codex with the install method and, for npm, npm prefix -g. This is a path diagnosis, not evidence that the installer lied.
Why does codex update fail on Windows with Get-FileHash?
One open report found that self-update spawned Windows PowerShell 5.1 where Get-FileHash could not load. Capture the final command failure and inspect that PowerShell environment. The preceding GitHub fallback warning alone is not the failure, and the report does not establish a universal product fix.
Is the GitHub Releases fallback warning itself an update failure?
No. The official standalone installer tries its primary release service and then GitHub Releases when metadata or an asset cannot be downloaded. Read the final installer result and verify the resolved CLI version. In the reported Windows case, the later PowerShell command failed, which is why that particular update did not finish.
What should I do if npm says EACCES while updating Codex?
Inspect npm prefix -g and the failing path first. If the global package location is not writable by your normal user, use npm’s documented user-owned Node installation approach or have the administrator repair that location. After that, retry npm install -g @openai/codex and verify the executable path and version. Avoid turning a single package update into a recursive permissions change across your home directory.
Does ENOSPC mean I should delete my Codex sessions?
No. npm uses ENOSPC for a failed write and says the cause can involve available space or write permission. Check the installation and cache volumes, then free space safely or resolve a quota. Back up data before any removal; deleting chat history is not an update repair. Retry only after the write condition has changed.
Can a custom npm mirror make Codex look stuck on an old version?
It can be one possible cause. Compare npm config get registry with the public registry and test with npm ping --registry=https://registry.npmjs.org/. If your environment permits it, use npm install -g @openai/codex --registry=https://registry.npmjs.org/ for that one attempt, then check the CLI path and version. A separate desktop app update still needs to be verified in the app.
Is npm install -g codex the right update command?
No. The official package is @openai/codex. A public issue report shows that the unscoped codex package led to an old dependency and an EBADENGINE warning. Use the scoped package name only in the npm environment that owns the CLI you launch.
Compare another message in the Codex error guide library. First check whether this is a Codex service-side problem → View live Codex status.
Sources
Each source lists what it is used to support. Sources are re-read on the review schedule, not continuously.
Supported installation methods and official release downloads.
Standalone installation and update guidance.
Official CLI command reference
Conditional self-update and command help.
General npm global package update behavior; the Codex-specific reinstall command follows the official README.
Upgrade a named installed cask.
User-owned install alternatives and platform limits.
The ENOSPC error text and the need to check available installation and temporary storage.
Testing the configured or explicitly selected package registry.
npm may use a custom registry rather than the public default.
Microsoft Get-Volume reference
Reading free space on a Windows installation volume.
Reading available space for a macOS or Linux installation filesystem.
Global npm installation EACCES report
Verbatim EACCES during a Codex npm install on a root-owned WSL prefix.
Wrong unscoped codex npm package report
Verbatim EBADENGINE after installing the unrelated unscoped codex package instead of @openai/codex.
Desktop update loop with proxy discussion
Reported macOS desktop update loop and a comment that disabling a local proxy helped one user.
Windows npm cleanup EPERM after successful update
A Codex CLI version may update even when npm warns that cleanup of a temporary directory failed.
The observed Windows update failure where codex update shells out to powershell.exe (5.1) regardless of the shell it was invoked from, the verbatim error block ('failed with status exit code', 'Could not download or verify', 'retrying from GitHub Releases'), and the reporter's unendorsed proposals — reported, not a confirmed fix.
The observed stale-backend failure after auto-update (CODEX_CLI_PATH pointing at a per-user copy not refreshed by the MSIX update) and the refresh_token_invalidated auth symptom — reported, not a confirmed fix.
Windows installer failure duplicate of
Duplicate report of the exact installer exit-code error.
Windows runtime relocation and companion binary report
Reported runtime path failures, matching-hash workaround and user-data backup advice.
Windows update EPERM on in-use codex.exe
Basis for the precaution to exit active clients before replacing binaries.
How this page is checked
- Evidence level
- Documentary - supported by official documentation
- Last reviewed
- 2026-10-02
- Content updated
- 2026-10-03
- Full version scope
- Official CLI installation and update methods cover Windows, macOS and Linux. Specific Get-FileHash and stale-desktop-runtime failures were reported on Windows; no universal fixed release is asserted.
- Symptoms indexed
-
- An update is reported as failing, or the version does not change after you try to update
- On Windows, codex update fails with a PowerShell / Get-FileHash error
- After a desktop auto-update, the tool points at a stale per-user backend or reports a logged-in session that no longer works
- You were told to update but are unsure which command applies to how you installed it
Reviewer note
Official README and linked issue reports re-read on 2026-10-02. Issue workarounds remain reported, not locally reproduced or endorsed as a universal fix.