---
title: "安装 Gemini CLI"
description: "Gemini CLI 安装方式：npm、npx、Homebrew、Docker / Podman sandbox、源码运行，以及安装后的第一轮验收。"
verifiedAt: "2026-05-09"
---

Gemini CLI 安装不应该从"把所有命令都试一遍"开始。先选一个与你的使用场景匹配的入口：长期本机使用装 npm 或 Homebrew，只试一次用 npx，隔离执行用 sandbox，开发 Gemini CLI 本身才从源码跑。

> [!NOTE]
> **这一篇用 12 分钟换什么**：完成安装、确认 `gemini` 命令可用、知道什么时候用 sandbox、知道源码运行只属于贡献者路径。安装完成不代表可以开始改真实项目，下一篇还要先处理认证。

## 1. 先选安装路径

| 场景 | 推荐入口 | 原因 |
| --- | --- | --- |
| 日常本机使用 | `npm install -g @google/gemini-cli` | 官方标准安装，启动稳定，适合长期使用 |
| macOS / Linux 包管理 | `brew install gemini-cli` | 适合已经统一使用 Homebrew 管 CLI 的机器 |
| 只试一次 | `npx @google/gemini-cli` | 不需要全局安装，适合临时体验 |
| 只想跑隔离环境 | Docker / Podman sandbox | 工具执行隔离更清楚 |
| 参与 Gemini CLI 开发 | 从 GitHub 源码运行 | 适合贡献者，不适合普通用户 |

```mermaid
flowchart TD
    Start["准备安装"] --> LongTerm{"长期本机使用?"}
    LongTerm -->|是| Npm["npm global 或 Homebrew"]
    LongTerm -->|否| Try{"只是临时试用?"}
    Try -->|是| Npx["npx @google/gemini-cli"]
    Try -->|否| Isolate{"需要隔离工具执行?"}
    Isolate -->|是| Sandbox["Docker / Podman sandbox"]
    Isolate -->|否| Source{"要开发 Gemini CLI 本身?"}
    Source -->|是| Dev["源码运行"]
    Source -->|否| Npm

    style Npm fill:#dcfce7,stroke:#22c55e
    style Sandbox fill:#fef3c7,stroke:#f59e0b
    style Dev fill:#fee2e2,stroke:#ef4444
```

## 2. 官方推荐环境

按官方 [installation.mdx](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/installation.mdx) 当前列出的具体要求：

| 项目 | 推荐配置 |
| --- | --- |
| Runtime | **Node.js 20.0.0+** |
| 操作系统 | **macOS 15+ / Windows 11 24H2+ / Ubuntu 20.04+** |
| 硬件（轻量任务） | 4 GB+ RAM（短会话、常见任务和编辑） |
| 硬件（重度任务） | 16 GB+ RAM（长会话、大代码库、深上下文） |
| Shell | Bash / Zsh / PowerShell |
| 地区 | 在 [Code Assist 支持地区](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) 内 |
| 浏览器 | Google OAuth 登录需要本机浏览器 + localhost 回跳 |
| 网络 | 需要互联网连接 |
| 项目工具链 | Git、包管理器、测试命令、语言 runtime（按你的项目而定） |

> [!IMPORTANT]
> **安装前先确认 Node 版本**：Gemini CLI 是 npm 包。Node 太旧时，不要靠反复重装 Gemini CLI 解决，先把 Node runtime 换到符合官方要求的版本。

## 3. npm 全局安装

```bash
npm install -g @google/gemini-cli
gemini
```

这是官方 get started 和 deployment 文档里的标准路径。适合日常本机使用。

安装后先验证命令是否真的在 PATH 里：

```bash
gemini --version
which gemini
```

如果 `gemini` 找不到，优先查 npm global bin 路径、shell PATH 和 Node 版本，不要马上切到另一种安装方式。

## 4. npx 临时运行

```bash
npx @google/gemini-cli
```

适合第一次试用或不想全局安装。缺点是每次启动的可控性和速度不如固定安装。

官方首页也给了从 GitHub 直接运行最新代码的方式：

```bash
npx https://github.com/google-gemini/gemini-cli
```

这个入口适合测试最新主分支，不适合作为团队默认安装方式。团队教程应该优先写稳定 npm 或 Homebrew 路径。

## 5. Homebrew

```bash
brew install gemini-cli
gemini
```

macOS / Linux 用户如果习惯用 Homebrew 管 CLI，可以选这个。

**MacPorts 备选**（同样靠系统包管理）：

```bash
sudo port install gemini-cli
```

**Anaconda 备选**（适合受限环境，把 Node 装在 conda 环境里）：

```bash
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli
```

> [!TIP]
> **不用本机装也能跑**：[Cloud Shell](/docs/gemini-cli/official/00-getting-started/04-cloud-shell) 和 [Cloud Workstations](https://cloud.google.com/workstations) 都**预装**了 Gemini CLI。第一次想试一下又不想动本机环境，可以从这两个入口起步。

## 6. Docker / Podman sandbox

官方安装页提供两种 sandbox 思路（具体镜像版本号请以 [官方 installation 页](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/installation.mdx) 当前版本为准）：

```bash
docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
```

或者本机已安装 CLI 后：

```bash
gemini --sandbox -y -p "your prompt here"
```

> [!WARNING]
> **sandbox 不是免责按钮**：它能帮助隔离工具执行，但不等于可以随便授权。涉及真实项目、密钥、删除、发布、支付、生产数据时，仍要先看计划、权限和影响范围。

## 7. 源码运行

如果你要参与 Gemini CLI 本身开发，才需要从源码运行：

```bash
npm run start
npm link packages/cli
gemini
```

普通用户不需要走源码路径。源码运行会引入仓库依赖、构建状态、分支变化和本地 link 问题；这不是学习 Gemini CLI 的必要成本。

## 8. 安装后验收

安装验收只看四件事：

1. `gemini --version` 能输出版本。
2. `gemini` 能启动交互式界面。
3. 当前 shell 能找到同一个 `gemini` 路径。
4. 你知道自己下一步要用哪种认证方式。

不要在认证之前进入真实仓库大改。安装只是把 CLI 放到机器上，真正决定能不能用的是账号、项目、权限、quota、隐私和工具确认策略。

## 9. 接下来去哪

<Cards>
  <Card title="认证方式" description="安装后先处理 Google OAuth、API key、Vertex AI 和 headless 场景。" href="/docs/gemini-cli/official/00-getting-started/02-authentication" />
  <Card title="Quickstart" description="认证完成后，再跑第一条只读分析和限定写入闭环。" href="/docs/gemini-cli/official/00-getting-started/03-quickstart" />
  <Card title="Release channels" description="需要 preview、latest、nightly 时，再单独看版本通道和发布节奏。" href="/docs/gemini-cli/official/00-getting-started/05-release-channels" />
</Cards>

## 官方来源

- [Gemini CLI Get Started](https://google-gemini.github.io/gemini-cli/docs/get-started/)
- [Gemini CLI Execution and Deployment](https://google-gemini.github.io/gemini-cli/docs/get-started/deployment.html)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
