How to Install OpenAI Codex CLI on Linux

When you need to understand an unfamiliar project or fix a failing test, Codex CLI lets you work with an AI coding assistant directly from your Linux terminal. You describe the task, and it can read project files, edit code, and run your development tools within the permissions you choose.

This guide explains how to install OpenAI Codex CLI on Linux, sign in, and try it in a project. We tested the standalone installer and npm package on Ubuntu 26.04 ARM64.

Quick Reference #

Prerequisites #

You need a Linux machine with an x86-64 or ARM64 processor, a terminal, and an internet connection. The standalone installer downloads a native executable, so you do not need Node.js for that method. Have curl and tar available before running it.

You also need a ChatGPT account with Codex access or an OpenAI API account with billing configured. Account and workspace restrictions can affect access. Using the normal OpenAI service sends prompts and relevant project context to OpenAI; installing the command locally does not make the model run offline.

Git is useful for reviewing and saving the changes Codex makes. Your project’s own tools, such as Python, Node.js, or a compiler, must also be installed if you want Codex to run them.

Step 1: Install Codex CLI #

Choose one installation method. Keeping a single installation avoids running an older copy from a different directory on your PATH.

Standalone Installer #

The official Linux installation instructions use this command:

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

Run it as your regular user. With the default paths, the installer puts the visible codex command in ~/.local/bin and keeps its release files under ~/.codex/packages/standalone. It can also add the binary directory to your shell’s startup file.

If you prefer to inspect the installer before executing it, download and open it first:

curl -fsSL https://chatgpt.com/codex/install.sh -o /tmp/codex-install.sh
less /tmp/codex-install.sh

Press q to leave the viewer. After reviewing the script, run it:

sh /tmp/codex-install.sh

Open a new terminal after installation. To make the default binary directory available in your current shell immediately, run:

export PATH="$HOME/.local/bin:$PATH"

Verify the installation:

codex --version

Our standalone installation returned:

codex-cli 0.167.1

Your version can be newer. The output confirms that the shell found the command and that the native executable runs on your system.

npm Alternative #

If you already use Node.js, you can install Codex through npm . Use a supported Node.js LTS release, such as Node.js 24. On Ubuntu, see our Node.js and npm installation guide .

Check that both commands are available:

node --version
npm --version

Then install the official package:

npm install -g @openai/codex@latest
codex --version

The package installs the same codex command. You do not need to install it again with the standalone script.

Step 2: Sign In to Codex #

ChatGPT Sign-In #

Start the browser sign-in flow:

codex login

Follow the browser instructions, then check the result:

codex login status

ChatGPT sign-in uses your account’s Codex access. API-key sign-in uses API billing instead. See OpenAI’s authentication documentation for current account and workspace requirements.

Headless Server or SSH Session #

If the Linux machine has no browser, use device code login:

codex login --device-auth

Open the printed URL on your own computer and enter the one-time code. Device code login may need to be enabled in your ChatGPT security settings or by your workspace administrator. Keep the code private.

API-Key Sign-In #

For an API account, create a key in the OpenAI API dashboard . In Bash, read it without displaying it or putting its value in shell history:

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

Step 3: Run Your First Project Task #

Start inside the project you want Codex to inspect. Replace the example path with an existing project directory:

cd ~/projects/my-app
git status --short
codex --sandbox read-only

Check the Git status before starting so you know which changes already belong to you. If there is work in progress, save a reviewed checkpoint before asking Codex to edit files.

For a first prompt, ask: “Explain the project structure and identify how to run its tests. Do not change any files.”

The explicit read-only sandbox keeps local command execution from editing the project. Codex can explain the files it reads, while test commands that need to write cache or build files may require additional permission. The sandbox and approval settings control command access separately from your written instructions.

Allow a Focused Change #

Exit the first session with /quit. To allow edits inside the project while keeping approval requests available, start another session:

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

Give it a task with a clear result, for example: “Add a test for the empty-input case in the parser, run the relevant test suite, and explain the diff.”

This mode allows local project edits and commands within the sandbox. It does not ask before every file change. Commands that need broader access can trigger approval requests; read those requests before accepting them. You can inspect the active permissions with /permissions and choose an available model with /model.

After Codex finishes, exit and review the changes with git diff :

git status --short
git diff --stat
git diff

Run the project’s tests yourself before committing. git diff shows changes to tracked files; inspect any new files listed by git status too.

To return to the most recent conversation later, run:

codex resume --last

Run a Task Without the Interactive Interface #

For a script or a single terminal request, use codex exec . This example explicitly keeps the repository read-only:

codex exec --sandbox read-only "Summarize the repository structure. Do not change files."

Codex writes progress to standard error and its final answer to standard output, so you can pipe the answer into another command. Non-interactive mode still needs authentication and model access.

Give Codex Project Instructions #

If you repeatedly explain the same build or test commands, put them in an AGENTS.md file at the project root. Codex reads this file as project guidance .

For example, a small JavaScript project could use:

# Project instructions

- Install dependencies with npm ci.
- Run npm test after changing application code.
- Keep changes focused on the requested task.
- Ask before adding a production dependency.

Use commands that actually exist in your project. These instructions guide the assistant; they do not replace filesystem permissions or test results.

You can also run /init inside a Codex session to generate a starting AGENTS.md, then edit it to match your project.

Updating Codex CLI #

For the standalone installation, rerun the official installer to get the latest release:

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

For an npm installation, update the package instead:

npm install -g @openai/codex@latest

Check the selected command and its version after updating:

command -v codex
codex --version

If the version did not change as expected, check for duplicate installations as shown in Troubleshooting.

Uninstalling Codex CLI #

Close Codex sessions before removing the installation. If you also want to remove its saved login, run codex logout first. The CLI and IDE extension can share credentials, so signing out can affect both.

For the default standalone paths, the following commands remove the executable link and downloaded standalone releases. Check these paths first if you used a custom installation directory. They leave your configuration and session history in place:

rm -f ~/.local/bin/codex
rm -rf ~/.codex/packages/standalone

If the installer added a PATH block to your shell startup file, open ~/.bashrc (Bash), ~/.zshrc (Zsh), or ~/.profile and delete the lines between # >>> Codex installer >>> and # <<< Codex installer <<<.

For npm, remove the global package:

npm uninstall -g @openai/codex

Troubleshooting #

codex: command not found after a standalone installation
Open a new terminal, or add the default binary directory to the current shell:

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

If that works but new terminals still cannot find it, add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc for Bash or ~/.zshrc for Zsh. Before adding it, look for an existing # >>> Codex installer >>> block in the same file.

npm install fails with EACCES
Your global npm prefix is not writable by your user. If you use a Node.js version manager, fix or reinstall that user-owned setup. Otherwise, you can give npm a user-owned global directory:

mkdir -p "$HOME/.local"
npm config set prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
npm install -g @openai/codex@latest

This changes the prefix for future global npm installs too. Keep the PATH entry in your shell’s startup file. Do not set a custom npm prefix alongside a version manager that manages its own prefix.

An older Codex version still runs
List all copies the shell can find:

type -a codex
npm list -g @openai/codex --depth=0

The first match on PATH is the one that runs. Remove the unwanted installation with its original installation method, then open a new terminal.

Browser sign-in does not complete over SSH
Use codex login --device-auth and complete the flow on a computer with a browser. Check whether your account or workspace permits device code login.

Codex cannot run tests or install dependencies
Read the error to distinguish a missing tool from a sandbox restriction. Install the project’s runtime and test dependencies yourself, or approve the specific access needed for the task. Use /permissions to review the active limits before starting another run.

Conclusion #

Start with a read-only project explanation, then give Codex one small change whose result you can check with Git and your tests. For another terminal-based coding assistant, see our guide to installing Claude Code on Linux .

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 1000+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page