Technical guide

How to fix Codex CLI update issues on Linux.

The reliable fix is to use a Node install owned by your user, or configure npm so global packages do not land in root-owned system directories.

OpenAI Codex CLI is a coding agent that runs locally in your terminal. You can install it with the official installer, npm, Homebrew, or a release binary. On Linux, one common npm-based update failure is not really a Codex problem. It is a global npm permissions problem.

When you run npm install -g @openai/codex@latest, npm may try to write into system-owned directories such as /usr/local/lib/node_modules. If those paths are owned by root, your normal user account cannot write there and npm exits with an EACCES: permission denied error.

The tempting workaround is sudo npm install -g. That usually makes the immediate error disappear, but it can leave root-owned files behind and create more permission conflicts later. A cleaner fix is to put global npm packages in a directory owned by your user.

Option 1: configure npm for user-owned installs

1. Create a directory for global npm packages

mkdir -p ~/.local

2. Point npm global installs at that directory

npm config set prefix ~/.local

3. Add the npm global bin directory to your PATH

For Bash users, add it to ~/.bashrc:

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

For Zsh users, add it to ~/.zshrc:

echo 'export PATH=~/.local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

4. Verify the npm prefix

npm config get prefix

The output should point to a directory inside your home folder, for example /home/yourusername/.local.

5. Install or update Codex CLI

npm install -g @openai/codex@latest
codex --version

At this point, npm should update Codex CLI without needing elevated privileges.

If you only need Codex CLI and do not want to manage npm global packages yourself, the official Codex installer is also an option:

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

Option 2: use nvm

If you work with multiple Node.js versions, Node Version Manager is usually the cleanest option. npm's own troubleshooting docs recommend using a Node version manager first because it installs Node.js inside your home directory, so npm global packages also stay under your user account.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
source ~/.bashrc

Then install Node.js and Codex CLI:

nvm install node
nvm use node
npm install -g @openai/codex@latest

This avoids system npm directories entirely because Node and global npm packages live under ~/.nvm/. If you choose nvm, do not also keep a custom npm prefix in ~/.npmrc; nvm warns that those settings are incompatible.

Troubleshooting

Multiple Codex binaries

If codex --version still reports an old version after an update, your shell may be finding another Codex binary first.

which -a codex
hash -r

Remove old or conflicting installs once you know where they came from:

npm uninstall -g @openai/codex

If you previously installed a standalone binary through another tool, remove only the specific old Codex binary after confirming the path:

rm ~/.cache/JetBrains/*/aia/codex/bin/codex-*

Ubuntu 22.04 GLIBC issues

On some Ubuntu 22.04 systems, a downloaded Linux binary can fail because of GLIBC compatibility. If that happens, use the musl build from the Codex release you want:

CODEX_VERSION=0.142.0
curl -LO "https://github.com/openai/codex/releases/download/rust-v$CODEX_VERSION/codex-x86_64-unknown-linux-musl.tar.gz"
tar xaf codex-x86_64-unknown-linux-musl.tar.gz
chmod +x codex-x86_64-unknown-linux-musl
mkdir -p ~/.local/bin
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex

Adjust CODEX_VERSION if the latest stable release has changed.

npm cache permission errors

If npm itself reports cache permission errors, repair ownership of your npm cache and then clean it:

sudo chown -R $(whoami) ~/.npm
npm cache clean --force

Team setup recommendations

For a team, the important part is consistency. Pick one installation method and document it in the onboarding guide.

Use one method consistently: npm with a user-owned prefix, nvm, the official installer, or a pinned standalone binary.
Pin versions in stable environments, for example npm install -g @openai/[email protected].
Document how to check the active binary with which -a codex.
Update regularly, but test the update path before asking the whole team to switch.

A simple setup script can make this repeatable:

#!/bin/bash
mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
npm install -g @openai/codex@latest

The practical rule

Do not rely on sudo npm install -g for day-to-day developer tooling. Put global npm packages somewhere your user owns, or use nvm so Node.js and npm stay inside your home directory.

That one change fixes Codex CLI update errors and prevents the same permissions problem from coming back with future global npm packages.