Install Gemini CLI on macOS, Windows, and Linux

Before you install: pick the auth rail first

This is out of order on purpose. Gemini CLI installs cleanly and then fails on the first request if you sign in the way most tutorials still describe.

Requirements

node -v      # must be v20.0.0 or higher
npm -v

npm install (every platform)

npm install -g @google/gemini-cli
gemini --version

This is the route Google documents first and the one that gets updates the day they ship. It works identically on macOS, Linux, Windows PowerShell, and WSL.

If it fails with EACCES

A global npm install writing into a root-owned prefix is the classic failure. Do not fix it with sudo: that leaves root-owned files in your npm tree and breaks every later install for your user.

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

npm install -g @google/gemini-cli

Release channels

npm install -g @google/gemini-cli@latest     # stable, weekly on Tuesdays
npm install -g @google/gemini-cli@preview    # weekly, unvetted
npm install -g @google/gemini-cli@nightly    # daily, from main

Stay on stable unless you are chasing a specific fix. Preview and nightly are explicitly documented as potentially containing regressions.

brew install gemini-cli

brew install gemini-cli
gemini --version

# later
brew upgrade gemini-cli

Homebrew is the tidier option on macOS and Linuxbrew: one command to install, one to upgrade, no npm prefix to reason about. The cost is version lag. In August 2026 the formula was on 0.46.0 while npm shipped 0.54.4, which is roughly two months of releases.

which -a gemini
brew list --versions gemini-cli
npm ls -g @google/gemini-cli

MacPorts

sudo port install gemini-cli

Install on Windows

There is no standalone Windows installer, no winget package, and no MSI. Windows uses npm, which means installing Node first.

winget install OpenJS.NodeJS.LTS

# open a NEW PowerShell window, then
node -v

npm install -g @google/gemini-cli
gemini --version

$env:GEMINI_API_KEY="YOUR_KEY"

[Environment]::SetEnvironmentVariable("GEMINI_API_KEY","YOUR_KEY","User")
# then open a new terminal

WSL

Inside WSL you are on Linux, so follow the Ubuntu instructions below. Do not install once on Windows and once in WSL and expect a shared config: they have separate home directories, so they have separate ~/.gemini directories and separate credentials.

Install on Ubuntu and other Linux

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
exec $SHELL -l

nvm install 22
nvm use 22
node -v

npm install -g @google/gemini-cli
gemini --version

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v

npm install -g @google/gemini-cli

Homebrew on Linux

brew install gemini-cli

Works, with the same version lag as macOS.

Run it without installing

npx @google/gemini-cli

# straight from main, for testing unreleased work
npx https://github.com/google-gemini/gemini-cli

npx is the right call for a one-off evaluation, a shared build machine, or a locked-down environment where a global install is not allowed. It is the wrong call for daily use: every invocation pays a resolution cost, and the cache is easy to lose.

Container sandbox

Gemini CLI can execute its tools inside a container rather than on your host, which is the isolation model to reach for on a repository you do not fully trust.

gemini --sandbox -y -p "explain this repository"

Anaconda

For restricted environments where you cannot install Node globally but can create a conda environment.

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

First run

export GEMINI_API_KEY="YOUR_KEY"
echo 'export GEMINI_API_KEY="YOUR_KEY"' >> ~/.zshrc

cd ~/code/your-project
gemini

/init

When the install goes wrong

Questions people ask

Keep reading