How to Fix Gemini CLI WSL Installation Issues

Installing Gemini CLI in Windows Subsystem for Linux (WSL) can sometimes be tricky due to the layered nature of the WSL environment. This guide covers the most common installation issues and their solutions.

Prerequisites

Before troubleshooting, verify you have the correct environment set up.

WSL Version Check

WSL 2 is strongly recommended for Gemini CLI. Check your version:

wsl --version

If you are on WSL 1, consider upgrading:

wsl --set-default-version 2

Node.js Version Requirement

Gemini CLI requires Node.js 18 or higher. Check your version:

node --version

If you need to install or upgrade Node.js in WSL, use nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload your shell configuration
source ~/.bashrc

# Install Node.js 20 (LTS recommended)
nvm install 20
nvm use 20
nvm alias default 20

Common Installation Errors and Solutions

Error: EACCES Permission Denied

This is the most common npm issue in WSL environments.

Symptoms:

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solution 1: Configure npm to use a user directory

# Create a directory for global npm packages
mkdir -p ~/.npm-global

# Configure npm to use this directory
npm config set prefix '~/.npm-global'

# Add to your PATH (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Now install Gemini CLI
npm install -g @google/gemini-cli

Solution 2: Use nvm (recommended)

If you installed Node.js using nvm, this permission issue typically does not occur because nvm manages packages in your home directory.

Error: ENOENT or Network Timeout

Symptoms:

npm ERR! code ENOENT
npm ERR! syscall connect
npm ERR! errno ENOENT

Or:

npm ERR! network timeout

Solution 1: Reset WSL networking

# From PowerShell (as Administrator), shut down WSL
wsl --shutdown

# Wait a few seconds, then restart WSL
wsl

Solution 2: Check DNS resolution

# Test DNS resolution
ping google.com

# If DNS fails, check your /etc/resolv.conf
cat /etc/resolv.conf

If DNS is not working, create or edit /etc/wsl.conf:

sudo nano /etc/wsl.conf

Add these lines:

[network]
generateResolvConf = false

Then create a manual DNS configuration:

sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 8.8.4.4" | sudo tee -a /etc/resolv.conf

Restart WSL after making these changes.

Solution 3: Configure npm registry

If you are behind a corporate firewall or proxy:

# Use a registry mirror
npm config set registry https://registry.npmmirror.com

# Or if your company has a private registry
npm config set registry https://your-company-registry.com

Error: Command Not Found After Installation

Symptoms:

bash: gemini: command not found

Solution: Fix your PATH configuration

First, find where npm installs global packages:

npm bin -g

This typically returns something like /home/username/.npm-global/bin or /home/username/.nvm/versions/node/v20.x.x/bin.

Add this directory to your PATH:

# For bash users
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify the installation:

which gemini
gemini --version

Network and Firewall Troubleshooting

WSL shares the Windows network stack, which can cause issues with firewalls and VPNs.

Windows Firewall Configuration

If npm cannot reach the internet, Windows Firewall may be blocking WSL:

1. Open Windows Security > Firewall & network protection
2. Click Allow an app through firewall
3. Ensure your WSL distribution (e.g., Ubuntu) has both Private and Public checked

VPN Interference

Some VPNs break WSL networking. If you use a VPN:

1. Try disconnecting from the VPN temporarily during installation
2. If the VPN is required, configure WSL to use the VPN's DNS servers
3. Some VPNs require specific WSL configuration - consult your VPN documentation

Proxy Configuration

If you are behind a corporate proxy:

# Set proxy for npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Set proxy for the shell (add to ~/.bashrc)
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

WSL vs Native Windows Installation

When deciding where to install Gemini CLI, consider your workflow.

Install in WSL When

• You do most development work in WSL
• You need Unix-based tooling and shell scripts
• You work with codebases that use Unix-style paths
• You prefer bash or zsh over PowerShell

Install in Native Windows When

• You primarily use Windows tools and editors
• You want the simplest installation experience
• You do not use WSL regularly
• You need to integrate with Windows-specific tooling

Installing in Both Environments

You can have separate installations in both WSL and native Windows. They will not conflict, but they will have separate configurations and authentication states.

Verifying Your Installation

After successful installation, verify everything works:

# Check the version
gemini --version

# Run authentication
gemini

# Select "Login with Google" and complete browser authentication

If browser authentication does not open automatically in WSL:

1. Copy the URL displayed in the terminal
2. Paste it into a browser on your Windows host
3. Complete the authentication
4. The CLI should detect the successful authentication

Authentication Troubleshooting in WSL

Browser Does Not Open Automatically

WSL may not be able to launch Windows browsers. Set a default browser:

# Add to ~/.bashrc or ~/.zshrc
export BROWSER='/mnt/c/Program Files/Google/Chrome/Application/chrome.exe'

Or manually copy the authentication URL to your Windows browser.

Authentication Token Not Persisting

If you need to re-authenticate every session:

1. Check that ~/.gemini directory exists and is writable:

ls -la ~/.gemini

2. Ensure file permissions are correct:

chmod 700 ~/.gemini
chmod 600 ~/.gemini/*

Using API Key Instead

If browser authentication is problematic, use an API key:

1. Get your API key from Google AI Studio

2. Set the environment variable:

# Add to ~/.bashrc or ~/.zshrc
export GEMINI_API_KEY="your-api-key-here"

3. Restart your shell and run Gemini CLI.

Quick Reference Commands

# Check Node.js version
node --version

# Check npm global bin directory
npm bin -g

# Install Gemini CLI
npm install -g @google/gemini-cli

# Verify installation
gemini --version

# Fix PATH (add to shell config)
export PATH="$(npm bin -g):$PATH"

# Reset npm configuration
npm config delete prefix
npm config delete proxy
npm config delete https-proxy

# Clear npm cache
npm cache clean --force

Next Steps

Once Gemini CLI is working in WSL:

• Learn how to leverage the 1M token context window for large codebase analysis
• Configure MCP integrations for extended capabilities
• Explore Google Search grounding for up-to-date information