---
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](/zh-Hant/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="/zh-Hant/docs/gemini-cli/official/00-getting-started/02-authentication" />
  <Card title="Quickstart" description="認證完成後，再跑第一條只讀分析和限定寫入閉環。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/03-quickstart" />
  <Card title="Release channels" description="需要 preview、latest、nightly 時，再單獨看版本通道和釋出節奏。" href="/zh-Hant/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)
