Installation Guide
Choose your operating system to get started with Gemini CLI installation.
Gemini CLI is a cross-platform command-line tool that brings the power of Google's Gemini AI models directly to your terminal. Whether you are on Windows, macOS, or Linux, installation takes less than five minutes once you have the prerequisites in place. This guide covers system requirements, all supported installation methods, platform-specific notes, troubleshooting for the most common install failures, and a verification checklist so you can confirm everything is working before you write your first prompt.
System Requirements
Before installing, confirm your machine meets these minimum requirements. Using an unsupported Node.js version is the single most common cause of installation failures.
| Component | Minimum | Recommended | Notes |
|---|---|---|---|
| Node.js | 16.0 | 20 LTS or 22 LTS | Check with node --version |
| npm | 7.0 | Latest | Included with Node.js |
| OS (Windows) | Windows 10 (64-bit) | Windows 11 | WSL2 also supported |
| OS (macOS) | macOS 11 Big Sur | macOS 14 Sonoma+ | Apple Silicon supported |
| OS (Linux) | Any modern distro | Ubuntu 22.04 LTS+ | x86-64 and ARM64 |
| Disk space | 50 MB | 200 MB (with cache) | For npm global install |
| Internet | Required | Required | For install and API calls |
Check your Node.js version
node --version
npm --version
If Node.js is not installed or is below version 16, download the latest LTS installer from nodejs.org, or use a version manager like nvm (Linux/macOS) or nvm-windows.
Prerequisites
- ✓Node.js 16.0 or higher
Required for npm installation
- ✓Google AI API Key
Get it from Google AI Studio
- ✓Terminal/Command Prompt
Basic command line knowledge
Quick Install (All Platforms)
If you have Node.js installed, you can use npm to install Gemini CLI:
# Install globally using npm
npm install -g @google/gemini-cli
# Verify installation
gemini --version
Platform-Specific Installation Steps
Windows 10 / 11
The recommended approach on Windows is to use the official Node.js installer from nodejs.org. If you prefer a Unix-style experience, install via Windows Subsystem for Linux (WSL2) and follow the Linux steps below.
- Download and run the Node.js LTS installer from nodejs.org. Accept all default options.
- Open a new Command Prompt or PowerShell window (do not use an old one — PATH changes require a new session).
- Run
node --versionand confirm the output is 16.x or higher. - Run the npm install command shown above.
- If you see a permissions error, run PowerShell as Administrator and repeat step 4.
# PowerShell — install and verify
npm install -g @google/gemini-cli
gemini --version
# Set your API key for the current session
$env:GOOGLE_AI_API_KEY="AIzaXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
macOS (Intel and Apple Silicon)
On macOS the cleanest approach is to manage Node.js with nvm or Homebrew. Avoid installing Node.js as root; instead keep it in your user home directory.
# Option A: install Node.js via Homebrew
brew install node
# Option B: install via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
nvm install --lts
# Then install Gemini CLI
npm install -g @google/gemini-cli
gemini --version
Apple Silicon (M1/M2/M3) is fully supported. If you encounter architecture errors, ensure you are using a native ARM64 build of Node.js rather than a Rosetta-emulated x86 version. Run node -p process.arch — it should output arm64.
Linux (Ubuntu / Debian / Fedora)
On Linux, avoid installing Node.js through the distribution's default package manager as it often provides an outdated version. Use the NodeSource repository or nvm instead.
# Install Node.js 20 LTS via NodeSource (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install Gemini CLI
npm install -g @google/gemini-cli
# If permission error, configure npm prefix (no sudo needed)
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
Alternative Installation Methods
Using Yarn
yarn global add @google/gemini-cli
Using Homebrew (macOS/Linux)
brew install gemini-cli
From Source
# Clone the repository
git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli
# Install dependencies
npm install
# Build and link
npm run build
npm link
Common Installation Issues
These are the top issues reported by new users, along with their solutions. Work through them in order if your installation does not proceed as expected.
Issue: "EACCES: permission denied" during npm install -g
This means npm is trying to write to a directory owned by root. Do not fix this with sudo — it creates further permission problems. Instead, change the npm global prefix to a user-owned directory.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @google/gemini-cli
Issue: "command not found: gemini" after install
The global npm bin directory is not in your PATH. Find it and add it.
# Find the npm bin directory
npm config get prefix
# Add /bin from that output to your PATH, e.g.:
echo 'export PATH=/usr/local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
Issue: Node.js version too old
# Install nvm, then use the latest LTS
nvm install --lts
nvm use --lts
nvm alias default node
Verify Your Installation
Run these commands after installation to confirm everything is working correctly before you proceed to API key configuration.
# 1. Check the gemini command is available
which gemini
# 2. Check the installed version
gemini --version
# 3. Print the help text
gemini --help
# 4. Run a test prompt (requires API key)
echo "Say hello" | gemini
Frequently Asked Questions
What version of Node.js is required for Gemini CLI?
Gemini CLI requires Node.js 16.0 or higher. We recommend Node.js 20 LTS or 22 LTS for the best performance and long-term support. Run node --version to check your current version and upgrade via nvm if needed.
How do I update Gemini CLI to the latest version?
Run the same install command again — npm will replace the existing version with the latest release. Use npm install -g @google/gemini-cli@latest to be explicit. Check the current installed version with gemini --version and the latest available version with npm show @google/gemini-cli version.
Can I install Gemini CLI without admin or sudo privileges?
Yes. Use nvm to install Node.js entirely in your home directory, then run npm install -g @google/gemini-cli without sudo. Alternatively, configure a custom npm prefix directory under your home folder as shown in the troubleshooting section above.