Codex update: how to update the CLI, and fixing EACCES
How codex update works for script, npm and Homebrew installs, the Update available prompt, pinning a version, and the EACCES error on a root-owned npm folder.
Run codex update. It works out how Codex was installed and runs that method’s own update: OpenAI’s install script again for a script install, npm install -g @openai/codex for npm, brew upgrade --cask codex for Homebrew on a Mac. Check the result with codex --version; the latest release on November 18, 2026 is 0.170.0. If the update fails with EACCES: permission denied, mkdir and a path under /usr/lib/node_modules or /usr/local/lib/node_modules, Codex was installed into a root-owned npm folder and your user cannot write there: update with the same sudo that installed it, or move Codex to OpenAI’s installer, which keeps it in your home folder.
The update command for each way of installing
codex update picks one of these, and you can run the same command yourself. As of release 0.170.0:
- OpenAI’s install script (Codex lives under
~/.codex/packages/standalone): run the install command again, which is also OpenAI’s documented update. - npm:
npm install -g @openai/codex. bun, pnpm and Vite+ installs get their owninstall -goradd -gequivalent. - Homebrew on macOS:
brew upgrade --cask codex. - A binary from a release archive (
codex-x86_64-unknown-linux-musl.tar.gzand its arm64 sibling, put on PATH by hand): no update command. Download the new archive and replace the file.
# install script, the same command as the first install
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# npm
npm install -g @openai/codex
codex --versionCopiedIf you are not sure which one you have, follow the codex on your PATH to its real file. A path inside ~/.codex/packages/standalone/releases is the install script; one inside a node_modules folder is npm:
readlink -f "$(command -v codex)"CopiedWhat codex update prints
In the CLI’s source, codex update announces the command it is about to run, runs it from /, and reports how it went:
Updating Codex via `npm install -g @openai/codex`...
...
🎉 Update ran successfully! Please restart Codex.CopiedA running Codex session keeps the old version until you quit and start it again. When the command fails, Codex ends with Error: `<command>` failed with status and the exit status, after the package manager’s own error. When it cannot tell how it was installed, it runs nothing:
Could not detect the Codex installation method. Please update manually: https://developers.openai.com/codex/cli/CopiedDetection is narrower than it looks. The npm, bun and pnpm launchers tell Codex which manager started it; a script install is recognised by its folder under ~/.codex; and Homebrew is recognised only on macOS, by a path under /opt/homebrew or /usr/local. A hand-placed binary, a build of your own, and, by a reading of the detection code, a Homebrew install on Linux all get that message. Update those the way you installed them.
The “Update available” prompt
An interactive codex session can open with a prompt before the chat starts:
Update available · 0.169.1 → 0.170.0
Release notes: https://github.com/openai/codex/releases/latest
1. Update now (runs `npm install -g @openai/codex`)
2. Skip
3. Skip until next versionCopied“Update now” runs the same command as codex update, so it fails the same way. “Skip” asks again next time; “Skip until next version” stays quiet until a newer release than the one shown. Per the update checker, Codex looks for a new release at most every 20 hours, in the background, so the prompt shows the result on the launch after the check, not the one that ran it. It reads GitHub’s latest release (Homebrew’s own cask listing for a Homebrew install), never offers an alpha, and shows no prompt when it cannot tell how Codex was installed, or when you start Codex with a prompt on the command line. A notice reading “Update available!” with “See https://github.com/openai/codex for installation options.” means the same thing as the error above: Codex could not tell how it was installed.
To stop the check, for instance on a server where you update on your own schedule, set this in ~/.codex/config.toml. OpenAI’s configuration reference describes it as “Check for Codex updates on startup (set to false only when updates are centrally managed).”
check_for_update_on_startup = falseCopiedEACCES: permission denied when updating an npm install
This is the failure most people searching for this meet. A reporter in openai/codex#21897 (Codex 0.167.0, Linux, npm 9.2.0) got:
Updating Codex via `npm install -g @openai/codex`...
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Error: `npm install -g @openai/codex` failed with status exit status: 243CopiedThe path varies with how Node was installed: with Ubuntu’s own nodejs package the global folder is /usr/lib/node_modules, and the message can name a folder inside it such as /usr/lib/node_modules/@openai. The cause is the same. Node from a system package puts npm’s global folder in a place only root can write, so Codex was installed with sudo npm install -g, and codex update runs npm as you, without sudo. Closing a similar report, a maintainer put it as an error that “occurs while npm creates its global directory, before Codex runs”, and asked the reporter to “use a global npm prefix your account can write to and try again.” What npm install -g does explains the global folder and why the error appears for any package. To see where npm installs on your machine:
npm prefix -g
ls -ld "$(npm root -g)"CopiedThree ways out, depending on how you want the machine to stay:
- Keep the system install and update it as you installed it.
sudo npm install -g @openai/codex. It works, but every future update needs the same, and the prompt’s “Update now” will keep failing; setcheck_for_update_on_startup = falseif you update this way. - Move to OpenAI’s installer. Remove the root-owned copy first, with
sudo, since the installer’s own offer to remove it runsnpm uninstall -g @openai/codexas you and would hit the same wall. Then install; after this,codex updateneeds no root. - Give npm a folder you own, with a Node version manager or by changing npm’s prefix, as npm’s own guide describes, then install Codex there without
sudo. Remove the root-owned copy too, or it may stay first on your PATH.
sudo npm uninstall -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
hash -r
codex --versionCopiedThe same report has a second case worth knowing: Codex installed under ~/.local with --prefix, while npm’s configured prefix was still /usr/local. codex update runs plain npm install -g, which writes to npm’s configured prefix, not to wherever the running Codex lives, so it failed there too. If you install with --prefix, update with the same --prefix, or set it once with npm config set prefix so the two agree.
Two copies of Codex, and an update that seems not to take
If codex update reports success and codex --version still prints the old number, there is a second copy earlier on your PATH. OpenAI’s installer warns about this itself when it finds an npm, bun or Homebrew copy: “Multiple managed Codex installs can be ambiguous because PATH order decides which one runs.” List every codex the shell can see:
type -a codexCopiedKeep one and remove the others with their own uninstall. One combination to watch: the installer links Codex as ~/.local/bin/codex, and npm’s guide suggests ~/.local as a user-owned npm prefix, which would put an npm copy at the same path. Use one or the other.
Other messages during an update
- “Missing optional dependency @openai/codex-linux-x64. Reinstall Codex: npm install -g @openai/codex@latest” (or
-linux-arm64). The npm package is a small launcher, and the program itself comes in a per-platform package npm installs as an optional dependency. When that package is not there, the launcher has nothing to run. Run the command it prints. - “Downloaded Codex archive checksum did not match expected digest.” The installer’s download did not match the digest published for the release, and it stops. Run it again.
- “Could not fetch GitHub release metadata for Codex … GitHub API may be unavailable or rate limited.” The installer could not get the release’s details from GitHub, as the message says. Wait and run it again.
Install a specific version, or go back one
The installer takes a version with --release or the CODEX_RELEASE variable (its help: “Version to install; overridden by --release.”). It accepts latest or a number such as 0.169.1, with or without the rust-v of the GitHub tag, and keeps the previous release on disk beside the active one. With npm, name the version after the package:
# install script
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_RELEASE=0.169.1 sh
# npm
npm install -g @openai/codex@0.169.1CopiedA pinned Codex still checks for updates, so on an interactive machine choose “Skip until next version” or turn the check off. Version numbers and dates are on the releases page; tags marked pre-release are alphas. Staying back has a cost: a new model can be refused to an old client, which is one of the causes of “model is not supported when using Codex with a ChatGPT account”.
On a server nobody is watching
A Codex that only runs from cron, a service or codex exec never answers a prompt, so it updates when you update it. Run codex update by hand or in your own maintenance job, then codex --version to confirm; a job started from cron needs the full path to codex, and for an npm install npm on its PATH too, for the reasons in the Codex on a Linux server guide. Update between runs rather than during one: a session already running keeps the old program until it ends. For a server where a release should not land unannounced, pin the version and set check_for_update_on_startup = false, which is the case OpenAI’s description of the setting names.