How to Install Gemini CLI on Windows, macOS, and Linux (Step-by-Step Guide)

Gemini CLI lets you access Google’s Gemini AI models directly from your terminal. It works across Windows, macOS, and Linux and fits into developer workflows for coding, debugging, automation, and research.

This guide covers system requirements, every installation method, authentication, and how to run your first prompt.

System Requirements (Check Before Installing)

Make sure your system meets these basics before installing.

• Windows 11 24H2 or newer
• macOS 15 or newer
• Ubuntu 20.04 or newer
• Node.js 20.0.0 or newer
• Bash, Zsh, or PowerShell
• 4GB RAM for light usage, 16GB+ for large codebases or long sessions
• An active internet connection

If Windows is your platform, confirm your build before installing anything. Press Win + R, type winver, and press Enter. A window pops up showing your current Windows version. If it reads below 24H2, install the latest Windows Update first.

Install Node.js

Gemini CLI runs on Node.js, so install it first if you don’t already have it.

Download the Node.js 20 LTS installer from the official Node.js site and run it. The installer sets up both node and npm on your system.

Once it finishes, confirm the install worked by running:

node -v

This prints the installed version. Confirm it reads v20 or higher.

Check npm as well:

npm -v

If both commands return version numbers, Node.js is ready. To update npm to its latest version, run npm install -g npm@latest.

Method 1: Install with npm (Recommended)

This method works on Windows, macOS, and Linux.

Open Terminal, or PowerShell on Windows, and run:

npm install -g @google/gemini-cli

Once the install finishes, verify it worked:

gemini --version

If a version number appears, the CLI is installed and ready to launch. You can also run gemini --help to confirm the command is recognized.

Method 2: Install with Homebrew (macOS and Linux)

If you already use Homebrew, install Gemini CLI with:

brew install gemini-cli

Then start the CLI:

gemini

Method 3: Install with MacPorts (macOS Only)

For MacPorts users, run:

sudo port install gemini-cli

Method 4: Install with Anaconda (Restricted Environments)

Use this option if your system restricts global npm installs.

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

Run Gemini CLI Without Installing (npx Method)

If you want to test Gemini CLI without installing anything, run:

npx @google/gemini-cli

This downloads and launches the latest version instantly, so once it finishes, you are already inside a session. Skip ahead to the authentication step below.

Use Gemini CLI in a Secure Sandbox (Docker)

Run Gemini CLI inside a container for isolation:

docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

If Gemini CLI is already installed locally, force sandbox mode instead:

gemini --sandbox -y -p "Your prompt here"

Start Gemini CLI

Start the CLI with a single command.

gemini

The first time you run this, a menu appears asking you to pick an authentication method. You won’t be able to send any prompt until you finish this step.

Authenticate Gemini CLI

The menu on screen lists a few sign-in options.

Option 1: Google Account (Best for Individuals)

This option requires no API key, includes a free tier, and updates models automatically. Just run gemini and complete the browser login that opens.

Option 2: Gemini API Key

This method skips signing in with a personal Google account.

Open Google AI Studio in your browser and sign in with a Google account. Go to the API Keys page. Google AI Studio can generate a project and key automatically for new users, or you can click Create API key if you don’t already have one.

Copy the key and keep it private. Do not paste it into public code, repositories, or chat messages, since anyone with the key can use the API resources tied to it.

Back in the terminal, on the menu from the previous step, select Use Gemini API Key and press Enter. Paste the key (right-click instead of Ctrl + V on Windows), then press Enter again to submit it. A message confirms the authentication succeeded.

Pasting the key manually works, but the CLI asks for it again in every new terminal session. To skip that, set it once as an environment variable instead:

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

On Windows PowerShell, use this format instead:

$env:GEMINI_API_KEY="YOUR_API_KEY"

Option 3: Vertex AI (Enterprise)

Vertex AI requires a Google Cloud project and additional configuration.

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Run Your First Prompt

Once authenticated, you can prompt Gemini CLI directly. Type a request like:

> Explain what Gemini CLI can do

Ask a direct question without entering the interactive session:

gemini -p "Explain this codebase"

Use it inside scripts with non-interactive mode:

gemini -p "Generate release notes" --output-format json

Analyze Files with Gemini CLI

To see Gemini CLI work with real files, set up a test folder first.

mkdir gemini-test
cd gemini-test

Inside this folder, create a plain text file named notes.txt and add a few lines of text to it.

Start Gemini CLI again from inside this folder, then reference the file by name using the @ symbol:

> @notes.txt Summarize this file and list the important points

If the file is in a different folder, use the full path instead:

> @/path/to/notes.txt Summarize this file

Which Gemini CLI Version Should You Use

Gemini CLI ships three release channels.

Stable releases publish weekly and pull in the previous week’s preview build plus bug fixes. This is the default channel for most users.

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

Preview releases also publish weekly but skip full vetting, so they can carry regressions.

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

Nightly releases publish daily and mirror the current state of the main branch, which means pending issues are expected.

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

Stick with stable for daily work. Switch to preview or nightly only if you need a feature that hasn’t landed in stable yet.

Common Installation Issues

A few common gaps trip up first-time installs.

• gemini command not found after installation, usually because Node.js is missing or below version 20
• Permission errors during a global npm install, fixed by using the Anaconda method or correcting npm permissions
• Skipping authentication or pasting an invalid API key, which stops the CLI from responding to any prompt
• Missing internet connection during install or at runtime, since Gemini CLI requires one at both stages

FAQs

Gemini CLI gives you fast, terminal-first access to Gemini models for coding, research, and automation. Install it once, authenticate, and it becomes part of your daily developer workflow with no browser tabs required.

Read More

• How Create Audio Clips with Gemini 2.0 Flash Model
• How to Fix Gemini Error 1013 “Something Went Wrong”
• How to Fix “Something Went Wrong (1100)” on Google Gemini
• How to Fix “Something Went Wrong (1097)” on Google Gemini
• How to Fix Gemini Error 1096 (Something Went Wrong)