Codex CLI on Linux: How to Install and Run It

Getting Codex CLI on Linux takes one command. Codex CLI is OpenAI's first-party terminal coding agent. It reads your repo, writes code, and runs tasks from the shell. This guide covers three install methods and the first-run setup.

The fastest path is npm: run npm install -g @openai/codex. That needs Node.js 18 or later. If you would rather skip Node, use the standalone installer script instead. Homebrew works too. Pick the one that fits your setup.

Below you get exact commands, a numbered walkthrough, and the fix for the number-one failure. Most first installs break because people grab the wrong npm package. We flag that early so you do not lose time to it.

Prerequisites for Codex CLI on Linux

Codex CLI is officially supported on Linux and macOS. On Windows it runs through WSL. You need a terminal and an OpenAI account to sign in.

If you install with npm, you also need Node.js 18 or later. The standalone installer script removes that requirement, so it is a good choice on minimal systems. Homebrew installs also skip the manual Node step.

You will need an OpenAI account to authenticate. Some usage requires a paid ChatGPT or API plan. Check current terms on OpenAI's site before you rely on it for daily work.

• A supported Linux distro (Ubuntu, Debian, Arch, or Fedora all work)
• Node.js 18+ only if you install via npm
• An OpenAI account for sign-in
• A terminal with normal user permissions

Install Node.js 18+ (Only for the npm Method)

Skip this section if you plan to use the standalone installer or Homebrew. You only need Node.js for the npm install path.

On Ubuntu or Debian, the distro repos can ship an older Node. Use the NodeSource setup script to get a current version. Run these two commands:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

sudo apt-get install -y nodejs

Then confirm the version with node --version. You want v18 or higher. If it prints something lower, your PATH may point at an older Node install.

The Three Ways to Install Codex CLI on Linux

There are three official install methods. All three give you the same codex command. Choose based on whether you already run Node.js or Homebrew.

Method 1, npm: run npm install -g @openai/codex. This is the common path for developers who already have Node.js 18+.

Method 2, standalone installer: run curl -fsSL https://chatgpt.com/codex/install.sh | sh. OpenAI ships this official script for Mac and Linux. It removes the Node.js dependency entirely.

Method 3, Homebrew: if you use Homebrew on Linux, install through it. Homebrew handles the binary and keeps it updated with your other formulae.

• npm: npm install -g @openai/codex (needs Node.js 18+)
• Standalone: curl -fsSL https://chatgpt.com/codex/install.sh | sh (no Node needed)
• Homebrew: install the codex formula on a supported system

Numbered Install Walkthrough

Here is the full npm path from a clean system. Swap step 3 for the standalone script if you want to skip Node.js.

Follow the steps in order. Each command runs in your normal terminal.

• 1. Confirm Node.js: run node --version and check it reads v18 or higher.
• 2. If Node is missing or too old, install it using the section above.
• 3. Install Codex: run npm install -g @openai/codex.
• 4. Verify the install: run codex --version. You should see a version number.
• 5. Start it: run codex in a project folder. It prompts you to sign in.
• 6. Sign in with your ChatGPT or OpenAI account, or supply an API key.

First Run and Sign-in

Open a terminal inside a project folder and type codex. On first launch it prompts you to authenticate.

The simplest option is to sign in with your ChatGPT or OpenAI account. Codex opens a browser flow, you approve access, and it returns to the terminal. Older docs reference a codex auth command, but recent versions prompt you automatically.

You can also authenticate with an API key instead of a browser sign-in. That suits headless servers and CI environments where no browser is available. Keep the key in an environment variable, never in committed code.

Across our own dev setup, the step that trips people up is not auth. It is grabbing the wrong package first. Once @openai/codex is installed, sign-in is quick.

Your First Codex CLI Commands

Once you are signed in, Codex works from inside a repo. It reads the code around you and acts on plain-language requests.

Start small. Ask it to explain a file or draft a function. Review what it proposes before you accept changes. Treat it like a fast pair programmer, not an autopilot.

Check codex --help for the current flags and subcommands. The tool updates often, so the built-in help is the most reliable reference for your installed version.

• codex --version confirms the install
• codex launches the agent in the current folder
• codex --help lists commands and flags for your version
• Run it inside a git repo so it can see your project files

Distro Notes: Ubuntu, Debian, Arch, and Fedora

The install commands are the same across distros. The only difference is how you get Node.js if you use the npm method.

On Ubuntu and Debian, use apt with the NodeSource script shown earlier, then run the npm install. The standalone installer script also works cleanly on both.

On Arch, install Node.js from the official repos with sudo pacman -S nodejs npm, then run npm install -g @openai/codex. The standalone script is a fine alternative.

On Fedora, install Node.js with sudo dnf install nodejs, then use npm. As with the others, the standalone installer script skips Node entirely.

• Ubuntu / Debian: NodeSource plus apt, then npm, or use the standalone script
• Arch: sudo pacman -S nodejs npm, then npm, or use the standalone script
• Fedora: sudo dnf install nodejs, then npm, or use the standalone script

Troubleshooting Common Codex CLI on Linux Errors

Most install problems fall into three buckets. Here is how to spot and fix each one.

Wrong package: if codex behaves oddly or is missing features, you likely installed the unscoped codex. That is an unrelated 2012 project. Uninstall it with npm uninstall -g codex, then install the correct one with npm install -g @openai/codex.

Command not found: if codex --version returns command not found, the global npm bin folder is not on your PATH. Find it with npm bin -g and add that folder to your PATH in your shell profile. Then open a new terminal.

Node version too old: if the install fails or the tool crashes, check node --version. Anything below 18 is unsupported. Upgrade Node, or switch to the standalone installer script that needs no Node at all.

• Wrong package: uninstall codex, install @openai/codex
• command not found: add the global npm bin folder to your PATH
• Old Node: upgrade to 18+ or use the standalone installer

Codex CLI Now Ships Inside the ChatGPT Linux App

OpenAI launched an official ChatGPT desktop app for Linux on August 11, 2026, in public preview. The Codex coding agent is built into it.

That means you can run Codex from the desktop app or from the terminal. The desktop version can work in local repos and read local files without uploading them elsewhere.

The Linux app is a public preview and may contain bugs, so OpenAI advises against mission-critical use for now. Officially tested distros include Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, and Debian 13, with RPM builds for Fedora.

For a scriptable, headless workflow, the standalone Codex CLI covered here remains the direct choice. Install it once with npm, the standalone script, or Homebrew, and you can drive it from any terminal or CI job. That is why the CLI stays the right tool for automation even after the desktop app arrived.