How to Install Codex CLI on Ubuntu 26.04, 24.04 and 22.04

OpenAI’s standalone installer is the cleanest way to install Codex CLI on Ubuntu because it avoids a Node.js dependency and keeps the command in a user-owned path. After authentication, Codex can inspect a repository, review changes, and run approved commands without leaving the terminal.

Use a package manager only when it already owns the rest of your developer toolchain. Pick one owner before installation: mixed methods can change which codex command wins on PATH and make updates or removal ambiguous.

Install Codex CLI on Ubuntu

Ubuntu’s APT repositories do not currently provide OpenAI Codex CLI as a package named codex. Choose one upstream method from the table instead of running sudo apt install codex.

Method	Package Owner	Best Fit
OpenAI standalone installer	Codex standalone updater	Recommended default with no Node.js or Homebrew dependency
npm package	npm (user prefix at ~/.local)	Workstations that already maintain a supported Node.js toolchain
Homebrew cask	Linux Homebrew	Systems where Homebrew already manages developer applications

Do not install the same command with multiple methods. Both the default standalone setup and the user-prefix npm setup can create ~/.local/bin/codex. Before changing an existing system, run type -a codex 2>/dev/null || true and identify every copy.

Method 1: Install Codex CLI with the OpenAI Installer

The standalone method supports Linux x86-64 and ARM64 systems, selects the matching release archive, verifies its checksum, and links the visible command to a versioned package under CODEX_HOME/packages/standalone/, which defaults to ~/.codex/packages/standalone/. Install curl and the TLS certificate bundle first:

sudo apt update
sudo apt install curl ca-certificates

The next command downloads OpenAI’s current installer and immediately executes it with sh. Use this direct path when that trust model matches your environment:

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

Here, -f makes HTTP errors fail, -sS keeps progress quiet while preserving errors, and -L follows redirects. For a review-first workflow, download and inspect the script before executing the local copy:

curl -fsSL https://chatgpt.com/codex/install.sh -o codex-install.sh
${PAGER:-less} codex-install.sh
sh codex-install.sh
rm -f -- codex-install.sh

The installer adds a marked PATH block to a supported shell profile when required. Open a new terminal, or refresh the path for the current Bash session, then verify the active command:

export PATH="$HOME/.local/bin:$PATH"
command -v codex
codex --version

A successful version check begins with codex-cli. The numeric version changes frequently, so compare it with the current upstream package instead of expecting a fixed example.

For unattended bootstrap scripts, CODEX_NON_INTERACTIVE=1 skips installer prompts:

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

This variable affects the installer only. It does not disable Codex runtime approvals, authentication, or sandbox controls.

Use a Custom Standalone Command Directory

The default command directory is ~/.local/bin. Set CODEX_INSTALL_DIR when you need a dedicated location, and preserve the same value for future reinstalls and removal:

mkdir -p "$HOME/.local/codex/bin"
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALL_DIR="$HOME/.local/codex/bin" sh
export PATH="$HOME/.local/codex/bin:$PATH"
codex --version

Changing CODEX_INSTALL_DIR moves the visible command, not the standalone package cache under CODEX_HOME.

Method 2: Install Codex CLI with npm

Check Ubuntu Node.js Compatibility

The current @openai/codex package declares Node.js 16 or newer as its compatibility floor. That floor is not a recommendation to deploy an end-of-life Node.js release; use an actively supported Node.js line for a maintained developer workstation.

Ubuntu Release	Default nodejs Candidate	npm Compatibility
Ubuntu 26.04	22.x	Meets the current package engine
Ubuntu 24.04	18.x	Meets the current package engine
Ubuntu 22.04	12.x	Too old; use the standalone method or install a current Node.js line

APT candidates can change through Ubuntu updates. Check the current package metadata on your system, and query npm’s live engine requirement before installation:

apt-cache policy nodejs npm
node --version
npm --version
npm view @openai/codex engines

If you need a maintained runtime, the Ubuntu Node.js installation guide covers Ubuntu packages, NodeSource, and NVM. Return after both node and npm work under your normal user account.

Install Codex CLI with a User Prefix

Use a home-directory prefix so npm does not require root access for the global package:

mkdir -p "$HOME/.local/bin"
grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc || printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.local/bin:$PATH"
npm install -g @openai/codex --prefix "$HOME/.local"

Avoid sudo npm install -g @openai/codex. A user prefix keeps the package and generated command owned by your account and makes later npm removal predictable.

Confirm that npm owns the package and the expected command is first on PATH:

npm list -g @openai/codex --depth=0 --prefix "$HOME/.local"
command -v codex
codex --version

Method 3: Install Codex CLI with Homebrew

Use this method when Linux Homebrew is already part of your toolchain. Homebrew itself requires Git; verify both commands before installing the cask:

git --version
brew --version

If Git is missing, refresh APT metadata and install it before continuing:

sudo apt update
sudo apt install git

If Homebrew is missing, follow the Ubuntu Homebrew installation guide first. Homebrew’s cask publishes Linux x86-64 and ARM64 artifacts, while Homebrew and its cask dependencies remain outside APT’s ownership.

brew install --cask codex
brew info --cask codex
command -v codex
codex --version

Authenticate Codex CLI

Codex supports ChatGPT sign-in and API-key sign-in. OpenAI’s authentication documentation explains the account and workspace controls for each option. The CLI stores its configuration under CODEX_HOME, which defaults to ~/.codex, and may keep credentials in ~/.codex/auth.json or the operating system credential store.

Treat auth.json as a secret. Do not copy it into a repository, support ticket, or shared backup. Codex CLI and Codex IDE integrations can share the same cached credentials, so signing out may affect both.

Sign In with ChatGPT

Start the browser-based sign-in flow directly:

codex login

For a headless or SSH session, device authentication is available only when your account or workspace permits it:

codex login --device-auth

Check the active session without changing it:

codex login status

To switch accounts, sign out and start a new login:

codex logout
codex login

Sign In with an API Key

For Platform-billed use, read the key without echoing it and pipe it to the login command:

read -rsp "OpenAI API key: " OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY

API-key authentication follows your OpenAI Platform billing and data controls rather than ChatGPT workspace entitlements. For a single non-interactive task, codex exec also accepts CODEX_API_KEY; scope that variable to the specific process instead of saving it in a shell profile.

Verify and Use Codex CLI on Ubuntu

Verify the active binary, authentication state, and local diagnostics before using Codex on a repository:

codex --version
codex login status
codex doctor

codex login status returns a nonzero status when no session exists, and codex doctor can do the same when it detects an authentication or environment problem. Read the diagnostic message rather than treating every nonzero result as a broken installation.

Run Interactive and Non-Interactive Prompts

Launch an interactive session from a project directory, optionally with an initial prompt:

codex
codex "explain the authentication flow in this project"

Use exec when a script or terminal workflow needs one non-interactive result:

codex exec "summarize this repository and list risky files"

Review Local Git Changes

Inside a Git repository, review uncommitted work, compare with a base branch, or inspect one commit:

codex review --uncommitted
codex review --base main
codex review --commit HEAD~1

A custom review prompt is a separate mode and cannot be combined with --uncommitted, --base, or --commit:

codex review "focus on authentication and file-permission risks"

Choose a Sandbox and Approval Policy

Start with read-only access when you only need analysis. Use workspace-write when Codex should edit files inside the current project, and keep approval prompts enabled for commands with side effects:

codex --sandbox read-only
codex --sandbox workspace-write --ask-for-approval on-request

Avoid --dangerously-bypass-approvals-and-sandbox for ordinary work. It removes both the approval gate and sandbox protection, so a mistaken prompt or untrusted repository instruction can have system-wide effects.

Update Codex CLI

Update the command with the same owner that installed it. If you are unsure, inspect every PATH match before proceeding:

type -a codex 2>/dev/null || true

Update the Standalone Install

Use the built-in updater for a default standalone install:

codex update
codex --version

You can also rerun the official installer. Reuse CODEX_INSTALL_DIR when the visible command lives in a custom directory:

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALL_DIR="$HOME/.local/codex/bin" sh
codex --version

Update the npm Install

npm install -g @openai/codex@latest --prefix "$HOME/.local"
codex --version

Update the Homebrew Install

brew upgrade --cask codex
codex --version

Troubleshoot Codex CLI

Codex Command Is Not Found

Inspect PATH and the expected user-level command before reinstalling anything:

printf '%s\n' "$PATH" | tr ':' '\n'
ls -l "$HOME/.local/bin/codex" 2>/dev/null || true
type -a codex 2>/dev/null || true

For the default standalone or npm layout, open a new terminal or run export PATH="$HOME/.local/bin:$PATH". Substitute your custom CODEX_INSTALL_DIR when applicable. For Homebrew, load the environment emitted by /home/linuxbrew/.linuxbrew/bin/brew shellenv as described in the Homebrew guide.

The Wrong or an Older Codex Version Runs

Multiple installs usually cause this symptom. List every match and resolve the active symlink before choosing which package owner to keep:

type -a codex 2>/dev/null || true
codex_path=$(command -v codex || true)
[ -n "$codex_path" ] && readlink -f "$codex_path"
hash -r

Remove the unwanted copy with its own package manager, start a fresh shell, then check the version again.

npm Reports an Unsupported Node.js Engine

An EBADENGINE warning or install failure means the active Node.js version does not meet the current package requirement:

node --version
npm view @openai/codex engines

Switch to a maintained Node.js line, or use the standalone install instead. Ubuntu 22.04’s default Node.js 12 candidate does not meet the current requirement.

npm Reports an EACCES Permission Error

Inspect npm’s current prefix and cache ownership before changing permissions:

npm_prefix=$(npm config get prefix)
npm_cache=$(npm config get cache)
printf 'prefix=%s\ncache=%s\n' "$npm_prefix" "$npm_cache"
ls -ld "$npm_prefix" "$npm_cache"

Use the --prefix "$HOME/.local" commands from the npm method rather than retrying with sudo. Do not recursively change ownership of system npm directories without first proving they were incorrectly assigned to your account.

Authentication Fails or Uses the Wrong Account

Replace the cached session through the CLI before touching local files:

codex login status
codex logout
codex login

If a workspace policy blocks sign-in, confirm the permitted authentication method with its administrator. Deleting ~/.codex is not a safe first fix because that directory may also contain sessions, configuration, and the standalone executable payload.

APT Cannot Locate Codex

This result is expected when you run sudo apt install codex. APT can install prerequisites such as curl, Git, or Node.js, but the Codex CLI package itself comes from the selected upstream owner.

The Installer Reports an Unsupported Architecture

Check the kernel architecture:

uname -m

The standalone installer recognizes x86_64/amd64 and arm64/aarch64. Do not force an x86-64 binary onto ARM64 or bypass the installer’s platform check; use a supported system or wait for an upstream asset for your architecture.

Remove Codex CLI

Run type -a codex 2>/dev/null || true first and remove each copy with the owner that created it. If you also plan to delete credentials, run codex logout while the command still exists.

Remove the Standalone Install

The default command is a symlink into the standalone package root. The following guard removes it only when the resolved target belongs to that root:

codex_link="$HOME/.local/bin/codex"
codex_home="${CODEX_HOME:-$HOME/.codex}"
standalone_root="$codex_home/packages/standalone"
if [ -L "$codex_link" ]; then
    codex_target=$(readlink -f "$codex_link")
    case "$codex_target" in
        "$standalone_root"/*)
            rm -f -- "$codex_link"
            rm -rf -- "$standalone_root"
            ;;
        *)
            printf 'Refusing unexpected target: %s\n' "$codex_target" >&2
            ;;
    esac
fi

For the custom directory example above, change only the first assignment to codex_link="$HOME/.local/codex/bin/codex". The package root remains the same.

Inspect any installer-created shell-profile markers before editing the profile:

grep -n -B2 -A2 'Codex installer' ~/.bashrc ~/.zshrc 2>/dev/null || true

Remove only the complete block between the paired Codex installer markers. Keep a generic ~/.local/bin PATH entry if npm or another user-level tool still relies on it.

Remove the npm Install

npm list -g @openai/codex --depth=0 --prefix "$HOME/.local"
npm uninstall -g @openai/codex --prefix "$HOME/.local"

Let npm remove its generated command. Do not add a separate rm ~/.local/bin/codex unless type -a and readlink prove the remaining file is an orphan from this npm prefix.

Remove the Homebrew Install

brew uninstall --cask codex

Inspect a Legacy Manual Binary

An older manual setup may have placed files under /usr/local/bin. Inspect their target, type, and package ownership before deleting anything:

ls -l /usr/local/bin/codex /usr/local/bin/update-codex-cli 2>/dev/null || true
file /usr/local/bin/codex /usr/local/bin/update-codex-cli 2>/dev/null || true
dpkg -S /usr/local/bin/codex /usr/local/bin/update-codex-cli 2>/dev/null || true

Only after confirming that both files are user-installed Codex artifacts, remove the exact paths:

sudo rm -f -- /usr/local/bin/codex /usr/local/bin/update-codex-cli

Reset Local Codex Data Safely

Remove the executable first, because the default ~/.codex directory also contains the standalone package payload. For a reversible reset, move the configured Codex home instead of deleting it immediately:

codex_home="${CODEX_HOME:-$HOME/.codex}"
backup="${codex_home}.backup.$(date +%Y%m%d%H%M%S)"
if [ -d "$codex_home" ]; then
    mv -- "$codex_home" "$backup"
    printf 'Backup created at %s\n' "$backup"
fi

This backup can contain credentials and session content, so keep it private and delete it only after confirming you no longer need recovery. An operating-system credential-store entry may remain; codex logout is the preferred way to clear shared CLI and IDE authentication.

Refresh Bash’s command cache and confirm that no other copy remains:

hash -r
type -a codex 2>/dev/null || true

Conclusion

Codex CLI is ready when codex --version identifies the active command and codex login status reports the intended authentication method. Keep updates and removal under the same package owner. For alternatives, Gemini CLI serves Google’s model ecosystem, while Claude Code provides an Anthropic-based terminal workflow.