안녕하세요, log 쌓는 MK 입니다.
운영 중인 오라클 Ubuntu ARM64 서버에서 OpenAI Codex CLI를 업데이트 한 후 다음과 같은 오류가 발생 했습니다.
Error: Missing optional dependency @openai/codex-linux-arm64.
Reinstall Codex: npm install -g @openai/codex@latest
이 오류는 단순히 @openai/codex 패키지가 설치되지 않은 상황과는 달랐는데요.
Codex CLI 본체는 설치되어 있지만, 현재 운영체제와 CPU 아키텍처에 필요한 플랫폼별 native 패키지가 설치되지 않은 상태에서 발생하는 것으로 확인했습니다.
이번 글에서는 Ubuntu ARM64 환경에서 실제로 발생한 사례를 기준으로 원인을 확인하고 해결하는 과정을 정리해 보려고 합니다.
1. 실제 문제가 발생한 환경
이번 사례의 환경은 다음과 같았습니다.
OS: Ubuntu
Architecture: aarch64
Node.js: v22.23.2
npm: 10.9.8
@openai/codex: 0.149.1
먼저 정확한 확인을 위해 CPU 아키텍처를 확인했습니다.
uname -m
결과는 다음과 같았습니다.
aarch64
따라서 서버가 ARM64 아키텍처임을 확인 했습니다.
Node.js와 npm 버전도 확인했습니다.
node --version
npm --version
결과:
v22.23.2
10.9.8
2. Codex 설치 자체는 성공한다
일반적인 설치 방법은 다음과 같습니다.
npm install -g @openai/codex@latest
이번 사례에서도 npm은 오류 없이 설치를 완료됐는데요.
added 1 package in 2s
하지만 설치가 성공했다고 해서 플랫폼별 실행 파일까지 모두 설치되었다고 볼 수는 없었습니다.
Codex 실행:
codex --version
결과:
Error: Missing optional dependency @openai/codex-linux-arm64.
Reinstall Codex: npm install -g @openai/codex@latest
즉, @openai/codex 자체는 설치되어 있지만 Codex가 실행에 필요한 @openai/codex-linux-arm64를 찾지 못하고 있었습니다.
3. Codex는 플랫폼별 패키지를 별도로 사용한다
이 오류를 이해하려면 Codex의 npm 패키징 구조를 알아야 합니다.
현재 Codex는 운영체제와 CPU 아키텍처에 따라 native 실행 파일을 별도의 플랫폼 패키지로 제공합니다.
공식 빌드 설정에는 다음과 같은 플랫폼 패키지가 정의되어 있습니다.
@openai/codex-linux-x64
@openai/codex-linux-arm64
@openai/codex-darwin-x64
@openai/codex-darwin-arm64
@openai/codex-win32-x64
@openai/codex-win32-arm64
Linux ARM64 패키지는 다음 target을 사용합니다.
aarch64-unknown-linux-musl
이는 OpenAI Codex 저장소의 공식 npm 패키지 빌드 설정에서 확인할 수 있습니다.
따라서 이번 서버에서는 다음 패키지가 필요합니다.
@openai/codex-linux-arm64
4. 실제로 ARM64 패키지가 설치되지 않았는지 확인
다음 명령으로 설치된 패키지를 확인할 수 있습니다.
npm ls -g @openai/codex @openai/codex-linux-arm64
문제가 발생한 환경에서는 다음과 같이 나왔습니다.
/home/ubuntu/.nvm/versions/node/v22.23.2/lib
└── @openai/[email protected]
여기에는 @openai/codex-linux-arm64가 없습니다.
따라서 Codex 본체는 설치되어 있지만 ARM64 플랫폼 패키지는 설치되지 않은 상태임을 확인할 수 있었습니다.
5. ARM64 패키지가 실제로 존재하는지 확인
그렇다면 @openai/codex-linux-arm64라는 패키지가 원래 존재하지 않는 것은 아닐까?
다음 명령으로 확인할 수 있습니다.
npm view @openai/[email protected] optionalDependencies
결과에는 다음과 같은 항목이 포함되어 있었습니다.
'@openai/codex-linux-arm64':
'npm:@openai/[email protected]'
즉 Codex 0.149.1은 @openai/codex-linux-arm64를 optional dependency로 정의하고 있으며, 실제 native 패키지는 다음 버전을 가리킵니다.
@openai/[email protected]
Codex의 공식 lockfile에서도 Linux ARM64 패키지가 os: [linux], cpu: [arm64]로 정의되고, 메인 패키지의 optional dependency로 연결되는 구조를 확인할 수 있습니다.
6. npm install을 다시 해도 해결되지 않는 경우
오류 메시지가 안내하는 대로 다음 명령을 반복해서 실행해 봤습니다.
npm install -g @openai/codex@latest
하지만 이번 사례에서는 이 방법으로 해결되지 않았습니다.
Codex를 제거한 뒤 다시 설치해도:
npm uninstall -g @openai/codex
npm install -g @openai/codex@latest
다시 확인하면:
npm ls -g @openai/codex @openai/codex-linux-arm64
결과는 여전히:
└── @openai/[email protected]
이었습니다.
7. --include=optional도 확인
npm의 optional dependency 처리 문제를 의심해 다음 방법도 시도했습니다.
npm install -g --include=optional @openai/codex@latest
하지만 이번 환경에서는 이 방법을 사용해도 @openai/codex-linux-arm64가 설치되지 않았습니다.
따라서 이번 사례에서는 단순히 npm의 optional 설치 옵션을 켜는 것만으로 해결되지 않았습니다.
실제로 Codex GitHub 저장소에는 Linux x64와 macOS ARM64 등에서도 동일한 Missing optional dependency 오류가 발생했다는 보고가 있었는데요.
따라서 이 오류를 특정 Ubuntu ARM64 환경만의 문제로 단정하기보다는 플랫폼별 optional dependency가 설치되지 않은 상황으로 보는 것이 더 정확해 보였습니다.
8. 해결 방법: 플랫폼 패키지를 명시적으로 설치
이번 사례에서는 필요한 ARM64 패키지를 직접 지정하여 설치했습니다.
다만 여기서 주의해야 할 점이 있었는데요.
문제의 Codex 버전이 0.149.1이었기 때문에 다음과 같이 버전을 맞춰 설치했습니다.
npm install -g "@openai/codex-linux-arm64@npm:@openai/[email protected]"
이 명령은 npm alias를 이용합니다.
구조를 풀어보면 다음과 같습니다.
@openai/codex-linux-arm64
↓
npm:@openai/[email protected]
즉 Codex가 찾는 패키지 이름은 @openai/codex-linux-arm64로 유지하면서, 실제 패키지는 @openai/codex의 Linux ARM64 variant를 설치합니다.
9. 특정 버전을 하드코딩할 때 주의할 점
위 명령에서 0.149.1은 이번 사례에서 실제로 설치된 Codex 버전입니다.
따라서 다른 버전의 Codex를 사용한다면 0.149.1을 그대로 복사해서 사용하면 안 됩니다.
예를 들어 최신 버전을 설치한 뒤 현재 npm registry의 최신 버전을 기준으로 ARM64 패키지를 설치하려면 다음과 같이 할 수 있습니다.
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"
이렇게 하면 특정 버전을 직접 입력하지 않고 현재 @openai/codex의 최신 버전을 조회하여 동일한 버전의 Linux ARM64 variant를 설치할 수 있습니다.
단, 메인 패키지와 플랫폼 패키지의 버전은 반드시 일치시키는 것이 중요합니다.
예를 들어 메인 패키지가:
@openai/[email protected]
이라면 플랫폼 패키지도:
@openai/[email protected]
를 사용해야 합니다.
10. 설치 결과 확인
설치가 끝난 뒤 다음 명령으로 확인합니다.
npm ls -g @openai/codex-linux-arm64
이번 사례에서는 다음과 같이 확인됐습니다.
/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
이제 @openai/codex-linux-arm64가 실제로 설치되어 있습니다.
11. 마지막으로 Codex 실행
플랫폼 패키지가 설치된 것을 확인한 후 다음 명령을 실행한다.
codex --version
정상적으로 버전이 출력되면 문제가 해결된 것으로 보면 됩니다.
이번 사례의 경우 핵심적인 확인 순서는 다음과 같습니다.
uname -m
npm ls -g @openai/codex @openai/codex-linux-arm64
npm view @openai/[email protected] optionalDependencies
그리고 ARM64 패키지가 설치되어 있지 않다면:
npm install -g "@openai/codex-linux-arm64@npm:@openai/[email protected]"
이후:
npm ls -g @openai/codex-linux-arm64
codex --version
순서로 확인합니다.
12. 정리
왜 저에게 이런 이슈가 생겼는지는 정확하게 모르겠습니다. 제가 별도로 업데이트를 한 것이 아니고 사용하던 환경에서 codex 를 입력해서 업데이트 알림을 보고 진행한 상태였습니다.
다만 버전 업데이트를 오래만에 진행하긴 했습니다. 하지만 저도 처음 발생한 상황이라 그냥 헤프닝으로 넘기고 후추 같은 이슈가 발생한다면 다시 한번 확인해 보려고 합니다.