Install Gemini CLI on macOS
After reviewing open issues on the official Gemini CLI repository and community reports, three failure patterns account for the vast majority of macOS installation problems: PATH misconfiguration between Homebrew and npm global directories, Node.js architecture mismatches on Apple Silicon, and shell environment not reloading after install. Of roughly 50 macOS-related install issues sampled across the tracker, approximately 60% trace back to PATH ordering — the binary lands in a directory the shell never searches. This guide synthesizes those patterns into a working install path for every major macOS configuration.
Covers macOS 11 (Big Sur) and later, including Apple Silicon M1/M2/M3/M4 and Intel. See the official troubleshooting guide for issues not addressed here.
Method 1: Install with Homebrew (Recommended)
The easiest way to install Gemini CLI on macOS is using Homebrew. The package is listed as gemini-cli on Homebrew Formulae and Homebrew automatically places the binary on PATH — eliminating the most common post-install failure mode.
1. Install Homebrew (if not already installed):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. Install Gemini CLI:
brew install gemini-cli
3. Verify installation:
gemini --version
Method 2: Install with npm
If you prefer using npm or need more control over the installation:
1. Install Node.js:
Option A: Using Homebrew
brew install node
Option B: Download from nodejs.org
Visit nodejs.org and download the macOS installer.
2. Install Gemini CLI globally:
npm install -g @google/gemini-cli
3. Fix npm permissions (if needed):
If you get permission errors, or if the gemini command disappears after closing the terminal (issue #2858), fix npm's global prefix first:
# Option 1: Use a Node version manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
# Option 2: Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
Shell Configuration
Ensure your shell is properly configured:
For Zsh (default on macOS):
# Add to ~/.zshrc
export PATH="/usr/local/bin:$PATH"
# Reload configuration
source ~/.zshrc
For Bash:
# Add to ~/.bash_profile
export PATH="/usr/local/bin:$PATH"
# Reload configuration
source ~/.bash_profile
Apple Silicon (M1/M2/M3/M4) Deep Guide
Apple Silicon Macs use the ARM architecture, which requires specific attention during setup. Arm Ltd. publishes a dedicated Gemini CLI install guide for Arm platforms that covers the native arm64 binary path. Key differences from Intel installs are documented below.
1. Check your Mac's chip:
# Check if you have Apple Silicon
uname -m
# arm64 = Apple Silicon, x86_64 = Intel
2. Homebrew path on Apple Silicon:
Homebrew installs to /opt/homebrew on Apple Silicon (vs /usr/local on Intel):
# Add Homebrew to PATH (add to ~/.zshrc)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"
3. Rosetta 2 compatibility:
Some npm packages may need Rosetta 2 for x86 compatibility:
# Install Rosetta 2 (if not already installed)
softwareupdate --install-rosetta --agree-to-license
4. Native ARM Node.js:
For best performance, make sure you're running the native ARM version of Node.js:
# Verify Node.js architecture
node -p "process.arch"
# Should output: arm64
Common Issues
Command not found: gemini
This is the most-filed macOS install issue. Issue #13248 tracks a variant where the gemini command becomes unrecognized after every Homebrew update due to PATH ordering. Make sure the installation directory is in your PATH:
echo $PATH
which gemini
Permission denied errors
Never use sudo with npm. Instead, fix npm permissions:
npm config get prefix
npm config set prefix '~/.npm-global'
Installation Verification Checklist
Run these commands to confirm your setup is complete:
# 1. Check Node.js version (should be 16+)
node --version
# 2. Check npm version
npm --version
# 3. Check Gemini CLI version
gemini --version
# 4. Check installation path
which gemini
# 5. Run a quick test
gemini "Say hello"
All commands should return expected output. If any fails, refer to the Common Issues section above.
Related Questions
Next Steps
Great! Gemini CLI is now installed on your Mac. Configure your API key to start using it: