Overview
After Node.js is verified in Step 1, the installer proceeds to Step 2/3: installing or updating the Gemini CLI package using npm. This page addresses issues that occur during thenpm install -g @google/gemini-cli command.
Error: Gemini CLI Installation Failed
Problem Description
After the npm installation attempts to run, you see this error:Root Cause
The installer verifies that thegemini command is available after running npm install -g @google/gemini-cli. If the command is not found, it indicates the installation failed.
Source code reference: gemini-cli-easy-installer-20250706.bat:78-97
Solution 1: Network Connection Issues
Diagnosis
The npm installation requires downloading the@google/gemini-cli package from the npm registry. Network issues can prevent this download.
Troubleshooting Steps
Verify internet connectivity
Test your internet connection:Expected output: You should see replies from Google’s servers.If the ping fails, check your network connection before proceeding.
Configure proxy settings (if needed)
If you’re behind a corporate proxy, configure npm:Contact your IT department for proxy server details.
Check Firewall Settings
Some firewalls may block npm:- Open Windows Defender Firewall
- Click “Allow an app through firewall”
- Ensure Node.js and npm are allowed
- If not listed, click “Allow another app” and add:
C:\Program Files\nodejs\node.exeC:\Program Files\nodejs\npm.cmd
Solution 2: Permission Issues
Diagnosis
Global npm installations (using-g flag) require write access to Node.js’s global directories. Without proper permissions, the installation will fail.
Run as Administrator
Run as administrator
Right-click the file and select “Run as administrator”.
This is the most common solution for permission-related installation failures.
Alternative: Configure npm for User-Level Installs
If you cannot run as administrator, configure npm to use a user-level directory:Solution 3: npm Cache Issues
Diagnosis
npm maintains a cache of downloaded packages. If this cache becomes corrupted, installations may fail even with good network connectivity and proper permissions.Clear npm Cache
Open Command Prompt as Administrator
- Press Win + X
- Select “Command Prompt (Admin)” or “Windows Terminal (Admin)”
- Click “Yes” on the UAC prompt
Clean the npm cache
Run the following command:Expected output:
The
--force flag is necessary to ensure complete cache cleanup, even if npm detects potential issues.Clear npm Cache Directory Manually
Ifnpm cache clean --force doesn’t resolve the issue, manually delete the cache:
Additional Troubleshooting
Check npm Configuration
Verify your npm configuration is correct:prefix(should point to Node.js global directory)proxyandhttps-proxy(should match your network)registry(should behttps://registry.npmjs.org/)
Reset npm Configuration
If configuration seems corrupted:Manual Installation
If the automatic installer continues to fail, install Gemini CLI manually:Create desktop shortcut manually (optional)
Follow the instructions in Shortcut Creation Troubleshooting to manually create the desktop shortcut.
Verification Steps
After resolving installation issues, verify Gemini CLI is working:Check Command Availability
Check Version
1.0.0 or similar)
Test Basic Functionality
Common Error Messages
EACCES: permission denied
EACCES: permission denied
Full error:Solution: Run the installer as administrator (Solution 2).
ENOTFOUND registry.npmjs.org
ENOTFOUND registry.npmjs.org
Full error:Solution: Check network connectivity and proxy settings (Solution 1).
ETIMEDOUT
ETIMEDOUT
Full error:Solution:
- Check firewall settings
- Verify internet connection stability
- Try again later (npm registry may be experiencing issues)
ECORRUPTCACHE
ECORRUPTCACHE
Full error:Solution: Clear npm cache (Solution 3).
Performance Tips
The installer notes that Gemini CLI installation may take 1-2 minutes:Be patient during installation. npm needs to download and install multiple dependencies. The process may appear to hang but is likely still working.
If Installation Seems Stuck
If installation appears to hang for more than 5 minutes:- Press Ctrl+C to cancel
- Clear npm cache (Solution 3)
- Run the installer again
Additional Resources
Still Having Issues?
If you’ve tried all solutions and Gemini CLI still won’t install:- Check
npm-debug.login your current directory for detailed error information - Verify Node.js installation:
node -vandnpm -v - Try installing a different global package to test npm:
npm install -g npm-check - Consider reinstalling Node.js completely
- Report the issue with full error logs on GitHub