Bug: codex fails with "Missing optional dependency @openai/codex-linux-x64" on Ubuntu x86_64

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #11744
• #12931

Powered by Codex Action

Downgrading Node resolved the issue.

The problem occurred with the following environment:

• Node: v24.14.0
• npm: 11.9.0
• Codex CLI: 0.110.0
• OS: Ubuntu 22.04.4 LTS (x86_64)

Running codex resulted in:

Error: Missing optional dependency @openai/codex-linux-x64

As a workaround, I downgraded Node using nvm:

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

After switching to:

• Node: v22.22.0
• npm: 10.9.4

codex works correctly.

This may indicate a compatibility issue with Node 24 / npm 11 and optional dependency resolution.

I've confirmed this was introduced in this PR.

Hmm, so if you go to https://www.npmjs.com/package/@openai/codex?activeTab=code and look at package.json, you should see:

  "optionalDependencies": {
    "@openai/codex-linux-x64": "npm:@openai/codex@0.110.0-linux-x64",
    "@openai/codex-linux-arm64": "npm:@openai/codex@0.110.0-linux-arm64",
    "@openai/codex-darwin-x64": "npm:@openai/codex@0.110.0-darwin-x64",
    "@openai/codex-darwin-arm64": "npm:@openai/codex@0.110.0-darwin-arm64",
    "@openai/codex-win32-x64": "npm:@openai/codex@0.110.0-win32-x64",
    "@openai/codex-win32-arm64": "npm:@openai/codex@0.110.0-win32-arm64"
  }

Based on the report of OS: Ubuntu 22.04.4 LTS (x86_64), this should install codex@0.110.0-linux-x64, which certainly seems to exist:

https://www.npmjs.com/package/@openai/codex/v/0.110.0-linux-x64

And if you look at the package.json for that specific tag, you see:

{
  "name": "@openai/codex",
  "version": "0.110.0-linux-x64",
  "license": "Apache-2.0",
  "os": [
    "linux"
  ],
  "cpu": [
    "x64"
  ],

so those os and cpu entries are what should enable npm to figure out that it is the appropriate optional dependency to install for the host machine.

Perhaps these tags/values changed in npm 11? If so, this seems like a bug/regression in npm.

npm install -g @openai/codex@0.111.0 "@openai/codex-linux-x64@npm:@openai/codex@0.111.0-linux-x64" && codex -v
will work for Ubuntu users

ChatGPT found some related issues regarding os and cpu information being pruned:

• https://github.com/npm/cli/issues/7961
• https://github.com/npm/cli/issues/8320

And then https://github.com/npm/cli/issues/8535 claims npm >= 11.10.1 fixes things?

@bolinfest I've tested with npm@11.11.0 but the issue is the same.

npm install -g @openai/codex@0.111.0 "@openai/codex-linux-x64@npm:@openai/codex@0.111.0-linux-x64" && codex -v will work for Ubuntu users适用于 Ubuntu 用户

Tested with npm@10.9.2 , the problem still exist

npm install -g @openai/codex@0.111.0 "@openai/codex-linux-x64@npm:@openai/codex@0.111.0-linux-x64" && codex -v will work for Ubuntu users

Tested with npm@11.11.0 , the problem solved.

I can confirm that the workaround for Ubuntu users also works for Debian on WSL2 (Windows 11), but with a critical caveat for WSL users regarding environment isolation.

Initially, the forced dependency command failed for me because my WSL terminal was defaulting to the Windows-installed version of Node/npm (located in /mnt/c/Users/...), which was causing a cross-platform binary mismatch when trying to resolve @openai/codex-linux-x64.

The fix for WSL users:

1. Isolate the environment: Install a native Linux version of Node inside WSL using nvm to ensure you aren't bridging to the Windows npm folders: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
2. Clear the npm prefix: Run npm config delete prefix to ensure global installs stay within the Linux file system.
3. Apply the Ubuntu workaround:

npm install -g @openai/codex@0.111.0 "@openai/codex-linux-x64@npm:@openai/codex@0.111.0-linux-x64"

1. Refresh the path: Run hash -r so the terminal points to the new Linux binary instead of the cached Windows path.

Once I was running a strictly native Linux Node environment, the @0.111.0 forced dependency resolved the "Missing optional dependency" error perfectly on Debian. Thanks for this thread, hope it helps someone else.

npm install -g @openai/codex@0.111.0 "@openai/codex-linux-x64@npm:@openai/codex@0.111.0-linux-x64"

this works thanks

hi, look this command
npm install -g @openai/codex@0.124.0 "@openai/codex-linux-x64@npm:@openai/codex@0.124.0-linux-x64" --registry=https://registry.npmjs.org/