Fastest Update: One Command
# Update to latest (recommended)
$ npm install -g @openai/codex@latest
# Confirm the version updated
$ codex --version$ brew upgrade codex
$ codex --versionAfter upgrading, your config file ~/.codex/config.toml and auth credentials ~/.codex/auth.json are left untouched — you typically don't need to reconfigure or re-authenticate.
Checking Your Current Version
# Check installed codex version
$ codex --version
# Check via npm global list (more detail)
$ npm list -g @openai/codex
# Check latest available version on npm
$ npm view @openai/codex versionPinning a Specific Version
Sometimes you need a specific version — for example when a new release introduced a breaking change, or when you need reproducibility in CI/CD:
# Install a specific version (replace x.x.x with target)
$ npm install -g @openai/[email protected]
# List all available versions
$ npm view @openai/codex versions --json
# Pin to exact version in CI (no range resolution)
$ npm install -g @openai/[email protected] --exactVersion Management in CI/CD
When installing Codex CLI in GitHub Actions or GitLab CI, specify an exact version rather than latest for stable, reproducible pipelines:
steps:
- name: Install Codex CLI
run: npm install -g @openai/[email protected]
# or accept auto-updates:
# run: npm install -g @openai/codex@latest2026 Notable Version Changes
| When | Change | Impact |
|---|---|---|
| February 2026 | Removed Chat Completions API support | All providers must now use wire_api = "responses"; custom provider configs in config.toml need updating |
| Q1 2026 | codex-mini-latest (o4-mini) becomes the default model |
Hard-coded model IDs in config.toml may no longer be valid; check your model setting |
| H2 2025 | /init command for AGENTS.md generation |
New feature — run /init to scaffold a project AGENTS.md |
| April 2025 | Initial open-source release | Base functionality established |
Custom provider users: If you have [model_providers] in config.toml and are upgrading across the February 2026 milestone, add wire_api = "responses" to each provider block or you'll get a config error. See the config.toml guide for full details.
Troubleshooting After Upgrade
Version number didn't change after upgrade
# Check which codex binary is running
$ which codex
# Check the npm global root is in your PATH
$ npm root -g
# Force PATH rehash (bash/zsh)
$ hash -rReconnecting after upgrade
Upgrades don't cause Reconnecting — if you're seeing connection issues after upgrading, it's the same proxy/network issue as before. See: Reconnecting troubleshooting guide.
config.toml errors after upgrade
If a major version upgrade breaks your config:
- Temporarily rename the config:
mv ~/.codex/config.toml ~/.codex/config.toml.bak - Run codex with defaults to confirm base functionality works
- Migrate your settings one by one to the new format
For the complete list of changes in each release: GitHub Releases ↗.
Frequently Asked Questions
How do I update Codex CLI to the latest version?
Run npm install -g @openai/codex@latest. Confirm with codex --version. Homebrew: brew upgrade codex.
How do I check my current version?
Run codex --version or npm list -g @openai/codex.
Do I need to reconfigure after upgrading?
Usually not. ~/.codex/config.toml and auth.json are untouched by npm upgrades. Exception: crossing the February 2026 breaking change requires updating custom provider configs.
Can I set up automatic updates?
Yes — add an alias to ~/.zshrc: alias codex-update="npm install -g @openai/codex@latest && codex --version". For automatic CI updates, use Dependabot or Renovate to track the npm package.