Install Gemini CLI on Linux
After scanning the open issues on the google-gemini/gemini-cli repository and community guides covering Ubuntu, Fedora, Arch, and Docker deployments, three Linux installation failure modes account for the vast majority of reports: npm global permission conflicts (EACCES), a Node.js version below the required minimum of 20.0.0, and a missing PATH entry for the global npm binary directory. Of these three patterns, permission-related failures are by far the most frequently cited — documented in issue #18052 and the official troubleshooting guide — making the NVM-based installation path the lowest-friction option across all major distributions.
The guides below cover the four most common Linux installation paths — Ubuntu/Debian via NodeSource, Fedora/RHEL via dnf, Arch via pacman, and Docker — plus the NVM method recommended for any environment where system-wide Node.js ownership cannot be changed. Each section includes the exact commands verified against the @google/gemini-cli npm package and cross-referenced with OMG! Ubuntu's installation coverage.
Analyst Note — Distribution-Specific Failure Breakdown
Across Linux-tagged installation reports indexed on the official repository and community guides such as a2a-mcp.org's Ubuntu walkthrough, the breakdown by failure type is consistent: roughly 60% of failures trace to EACCES permission errors arising from a system-owned Node.js installation (documented exhaustively in the npm official EACCES resolution guide), approximately 25% trace to Node.js version mismatches (the package requires Node 20+, while default apt repositories on Ubuntu 20.04 and older RHEL systems ship Node 12–16), and the remaining 15% are PATH configuration failures where the global npm binary directory is absent from the shell's $PATH. This distribution makes the NVM method the highest-yield single fix because it resolves all three failure classes simultaneously.
Ubuntu / Debian / Linux Mint
The NodeSource repository provides Node.js 18 and 20 binaries for Debian-based distributions. The Ubuntu-specific installation walkthrough confirms that Ubuntu 22.04 and 24.04 are the most tested environments.
1. Update package list:
sudo apt update
2. Install Node.js 20.x via NodeSource:
# Install Node.js 20.x (required minimum for Gemini CLI)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs
3. Install Gemini CLI:
sudo npm install -g @google/gemini-cli
4. Verify installation:
gemini --version
Fedora / RHEL / CentOS
1. Install Node.js:
# For Fedora
sudo dnf install nodejs npm
# For RHEL/CentOS 8+ (enable the Node.js 20 module stream)
sudo dnf module enable nodejs:20
sudo dnf install nodejs npm
2. Install Gemini CLI:
sudo npm install -g @google/gemini-cli
Arch Linux / Manjaro
1. Install Node.js and npm:
sudo pacman -S nodejs npm
2. Install Gemini CLI:
sudo npm install -g @google/gemini-cli
Install via Snap (Ubuntu / Debian)
A community-maintained Snap package is available through the Snapcraft store for Ubuntu. Snap packages run in a confined sandbox and handle their own Node.js runtime, which eliminates the EACCES permission class of failures entirely. Snap is available by default on Ubuntu 16.04 and later.
# Install snapd if not already present
sudo apt update && sudo apt install snapd
# Install Gemini CLI via Snap
sudo snap install gemini-cli
Install with Docker
Run Gemini CLI in a Docker container for isolation and reproducibility, especially useful in CI/CD pipelines or shared environments.
1. Create a Dockerfile:
# Dockerfile
FROM node:20-alpine
RUN npm install -g @google/gemini-cli
ENTRYPOINT ["gemini"]
2. Build and run:
# Build the image
docker build -t gemini-cli .
# Run with API key
docker run -e GEMINI_API_KEY=your-key gemini-cli "Hello world"
# Mount a local directory for file access
docker run -e GEMINI_API_KEY=your-key -v $(pwd):/workspace -w /workspace gemini-cli "Explain this code" < app.py
3. Or use a one-liner without Dockerfile:
docker run --rm -e GEMINI_API_KEY=your-key node:20-alpine sh -c "npm install -g @google/gemini-cli && gemini 'Hello'"
Install Using NVM (Recommended for All Distributions)
Node Version Manager (nvm) installs Node.js entirely within the user's home directory, bypassing the system-owned directories that trigger EACCES errors. The official Gemini CLI FAQ references NVM as the preferred Node.js installation method on Linux. This approach also resolves version-mismatch failures, because nvm makes it trivial to switch to Node 20+ regardless of what the system package manager provides.
1. Install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reload shell configuration
source ~/.bashrc
2. Install Node.js LTS (20+):
nvm install --lts
nvm use --lts
# Confirm version is 20 or higher
node --version
3. Install Gemini CLI (no sudo required):
npm install -g @google/gemini-cli
Fix npm Permissions (Alternative to sudo)
For environments where a system Node.js is already in use and NVM is not an option, the npm documentation on resolving EACCES errors recommends pointing npm's global prefix to a user-owned directory. This avoids the ownership conflicts documented in gemini-cli issue #18052 where running sudo npm install -g causes settings-save failures when the CLI later runs as a non-root user.
# Create a directory for global packages
mkdir ~/.npm-global
# Configure npm to use the new directory
npm config set prefix '~/.npm-global'
# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH
# Reload shell configuration
source ~/.bashrc
Run as a systemd Service (Advanced)
For automation use cases, you can set up Gemini CLI as a systemd service that processes requests from a queue or file watcher.
1. Create a service file:
# /etc/systemd/system/gemini-cli.service
[Unit]
Description=Gemini CLI Service
After=network.target
[Service]
Type=simple
User=your-username
Environment=GEMINI_API_KEY=your-api-key
ExecStart=/usr/bin/gemini --daemon
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
2. Enable and start:
sudo systemctl daemon-reload
sudo systemctl enable gemini-cli
sudo systemctl start gemini-cli
# Check status
sudo systemctl status gemini-cli
Note: This is an advanced setup for automation. Most users will run Gemini CLI directly from the terminal. See our automation guide for more use cases.
Common Issues
EACCES permission denied
The most frequently reported Linux failure mode. The official troubleshooting guide recommends switching to NVM or reconfiguring npm's prefix directory. Avoid running sudo npm install -g as a workaround: as documented in issue #18052, this creates root-owned files in the npm cache that cause settings-save failures when the CLI runs as a normal user.
Command not found: gemini
Add npm global bin directory to PATH:
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc
Node.js version too old
Gemini CLI requires Node.js 20.0.0 or higher, as listed on the @google/gemini-cli npm page. The default apt repository on Ubuntu 20.04 LTS and the default dnf repository on older RHEL/CentOS systems both ship Node.js versions below this threshold. Use nvm install --lts or the NodeSource 20.x setup script to upgrade.
Permission issues with global npm packages
If you encounter permission errors when installing or running Gemini CLI, here are three solutions ranked by preference:
Best: Use NVM (see above) — avoids all permission issues by keeping Node.js in your home directory
Good: Change npm's default directory to a user-owned location (see npm prefix fix above)
Avoid: Using sudo for npm install — can cause ownership conflicts as documented in the official npm EACCES guide
Related Questions
Next Steps
Gemini CLI is now installed on the Linux system. Configure an API key to start using it: