Hi, I’m MK, and this is where I keep my logs.
After updating OpenAI Codex CLI on my Oracle Cloud Ubuntu ARM64 server, I ran into the following error.
Error: Missing optional dependency @openai/codex-linux-arm64.
Reinstall Codex: npm install -g @openai/codex@latest
This was different from the case where the @openai/codex package simply isn’t installed.
The Codex CLI itself was installed, but the platform-specific native package for my OS and CPU architecture was missing.
In this post, I’ll walk through how I confirmed the cause and fixed it, based on the case I actually ran into on Ubuntu ARM64.
1. The environment where the problem occurred
My environment was as follows.
OS: Ubuntu
Architecture: aarch64
Node.js: v22.23.2
npm: 10.9.8
@openai/codex: 0.149.1
First, I checked the CPU architecture to be sure.
uname -m
The result:
aarch64
This confirmed the server is ARM64.
I also checked the Node.js and npm versions.
node --version
npm --version
Result:
v22.23.2
10.9.8
2. The Codex installation itself succeeds
The usual way to install it is:
npm install -g @openai/codex@latest
In my case, npm finished the installation without any errors.
added 1 package in 2s
But a successful install doesn’t mean the platform-specific executable was installed as well.
Running Codex:
codex --version
Result:
Error: Missing optional dependency @openai/codex-linux-arm64.
Reinstall Codex: npm install -g @openai/codex@latest
In other words, @openai/codex was installed, but it couldn’t find @openai/codex-linux-arm64, which it needs to run.
3. Codex uses separate platform-specific packages
To understand this error, you need to know how Codex is packaged on npm.
Codex currently ships its native executables as separate platform packages, one for each operating system and CPU architecture.
The official build configuration defines the following platform packages.
@openai/codex-linux-x64
@openai/codex-linux-arm64
@openai/codex-darwin-x64
@openai/codex-darwin-arm64
@openai/codex-win32-x64
@openai/codex-win32-arm64
The Linux ARM64 package uses this target:
aarch64-unknown-linux-musl
You can find this in the official npm package build configuration in the OpenAI Codex repository.
So my server needs this package:
@openai/codex-linux-arm64
4. Checking that the ARM64 package really wasn’t installed
You can check the installed packages with this command.
npm ls -g @openai/codex @openai/codex-linux-arm64
In the environment with the problem, the output looked like this.
/home/ubuntu/.nvm/versions/node/v22.23.2/lib
└── @openai/[email protected]
@openai/codex-linux-arm64 is nowhere to be seen.
So the Codex main package was installed, but the ARM64 platform package was not.
5. Checking that the ARM64 package actually exists
Could it be that @openai/codex-linux-arm64 doesn’t exist at all?
You can check with this command.
npm view @openai/[email protected] optionalDependencies
The result included the following entry.
'@openai/codex-linux-arm64':
'npm:@openai/[email protected]'
So Codex 0.149.1 does define @openai/codex-linux-arm64 as an optional dependency, and the actual native package points to this version:
@openai/[email protected]
The official Codex lockfile shows the same structure too: the Linux ARM64 package is defined with os: [linux] and cpu: [arm64], and is linked as an optional dependency of the main package.
6. When running npm install again doesn’t help
I tried running the command the error message suggests, several times.
npm install -g @openai/codex@latest
But in my case, that didn’t fix it.
Even after removing Codex and installing it again:
npm uninstall -g @openai/codex
npm install -g @openai/codex@latest
Checking again:
npm ls -g @openai/codex @openai/codex-linux-arm64
The result was still:
└── @openai/[email protected]
7. Trying --include=optional as well
Suspecting how npm handles optional dependencies, I also tried this.
npm install -g --include=optional @openai/codex@latest
But even with this option, @openai/codex-linux-arm64 was not installed in my environment.
So in my case, simply turning on npm’s optional install flag was not enough.
The Codex GitHub repository also has reports of the same Missing optional dependency error on Linux x64, macOS ARM64 and other platforms.
So rather than treating this as a problem specific to my Ubuntu ARM64 setup, it seems more accurate to see it as a case where the platform-specific optional dependency doesn’t get installed.
8. The fix: install the platform package explicitly
In my case, I fixed it by installing the required ARM64 package directly.
There’s one thing to watch out for, though.
The Codex version I had was 0.149.1, so I matched the version when installing.
npm install -g "@openai/codex-linux-arm64@npm:@openai/[email protected]"
This command uses an npm alias.
Broken down, it looks like this.
@openai/codex-linux-arm64
↓
npm:@openai/[email protected]
That is, the package name stays @openai/codex-linux-arm64, which is what Codex looks for, while the package actually installed is the Linux ARM64 variant of @openai/codex.
9. Be careful when hardcoding a specific version
In the command above, 0.149.1 is the Codex version that was actually installed in my case.
If you’re on a different version of Codex, don’t copy 0.149.1 as is.
For example, if you want to install the latest version and then install the ARM64 package matching the latest version in the npm registry, you can do this.
npm install -g @openai/codex@latest
CODEX_VERSION=$(npm view @openai/codex version)
npm install -g "@openai/codex-linux-arm64@npm:@openai/codex@${CODEX_VERSION}-linux-arm64"
This way you don’t type a version by hand: it looks up the current version of @openai/codex and installs the Linux ARM64 variant of that same version.
Still, it’s important to keep the main package and the platform package on the same version.
For example, if the main package is:
@openai/[email protected]
then the platform package must be:
@openai/[email protected]
10. Checking the installation result
Once the installation is done, check it with this command.
npm ls -g @openai/codex-linux-arm64
In my case, the output was:
/home/ubuntu/.nvm/versions/node/v22.23.2/lib
├── @openai/codex-linux-arm64@npm:@openai/[email protected]
└─┬ @openai/[email protected]
└── @openai/codex-linux-arm64@npm:@openai/[email protected] deduped
Now @openai/codex-linux-arm64 is actually installed.
11. Finally, run Codex
After confirming the platform package is installed, run this command.
codex --version
If the version prints normally, the problem is solved.
In my case, the key checks go in this order.
uname -m
npm ls -g @openai/codex @openai/codex-linux-arm64
npm view @openai/[email protected] optionalDependencies
And if the ARM64 package isn’t installed:
npm install -g "@openai/codex-linux-arm64@npm:@openai/[email protected]"
Then:
npm ls -g @openai/codex-linux-arm64
codex --version
Check in that order.
12. Wrapping up
I don’t know exactly why this happened to me. I didn’t update anything on my own: I ran codex in the environment I’d been using, saw the update notice, and went ahead with it.
It had been a while since my last update, though. Since this was the first time I’d hit this, I’m treating it as a one-off, and if a similar issue shows up later I’ll look into it again.