---
title: "卸载"
description: "Gemini CLI 卸载方式：npx cache、npm global、Homebrew 和 MacPorts。"
verifiedAt: "2026-05-09"
---

卸载方式取决于你当初怎么运行 Gemini CLI。

> [!WARNING]
> 卸载 CLI 不等于删除配置。`~/.gemini`、项目 `.gemini/`、trusted folders、settings、skills、extensions、memory 和 shell 环境变量需要单独判断。

## 先确认安装来源

| 运行方式 | 清理对象 | 验证命令 |
| --- | --- | --- |
| `npx @google/gemini-cli` | npm `_npx` cache | `npm config get cache` |
| `npm install -g` | 全局 npm package | `npm list -g @google/gemini-cli` |
| Homebrew | brew formula | `brew list --versions gemini-cli` |
| MacPorts | port package | `port installed gemini-cli` |
| 源码运行 | 本地 clone、build 产物、shell alias | `command -v gemini` |

## npx

`npx` 不会永久安装包，而是使用 npm cache。要清理 Gemini CLI 的 npx 临时包，需要清理 `_npx` cache。

macOS / Linux：

```bash
rm -rf "$(npm config get cache)/_npx"
```

Windows PowerShell：

```powershell
Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force
```

## npm global

如果用全局 npm 安装：

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

## Homebrew

```bash
brew uninstall gemini-cli
```

## MacPorts

```bash
sudo port uninstall gemini-cli
```

## 卸载前检查

如果只是版本旧，不一定要卸载，直接更新通常更合适：

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

如果 `gemini` 仍然指向旧版本，先查 `command -v gemini` 和 shell alias/function。很多“卸载失败”其实是 PATH 中还有另一个安装来源。

## 卸载不等于清空配置

卸载 package 只移除 CLI 程序或缓存，不会自动删除你的 `~/.gemini` 配置、会话、trusted folders、settings、skills、extensions 或 memory。排查问题时要区分：

- 程序包问题：卸载 / 重装 CLI。
- 配置污染：检查 `~/.gemini/settings.json`、项目 `.gemini/settings.json`。
- 会话或 memory 问题：检查 `/memory show`、session 恢复来源。
- npx cache 问题：清 `_npx` cache。

如果只是想重置一个项目，优先检查项目目录里的 `.gemini/`，不要直接删全局 `~/.gemini`。全局目录可能包含所有项目共享的配置和记忆。

## 清理决策

| 目标 | 推荐动作 |
| --- | --- |
| 想升级到最新 stable | 直接更新，不先卸载 |
| `npx` 老是跑旧包 | 清 `_npx` cache |
| npm 全局版本坏了 | `npm uninstall -g` 后重装 |
| 多安装源冲突 | 逐个卸载非目标来源，再确认 `command -v gemini` |
| 项目配置污染 | 临时移开项目 `.gemini/`，不要直接删全局目录 |
| 要换账号或认证方式 | 先看认证页和 settings，不把卸载当退出登录 |

## 安全重置顺序

如果你确实想做“干净重装”，建议按影响范围从小到大处理：

1. 在空目录运行 `gemini --version`，确认是否只有当前项目异常。
2. 临时重命名项目 `.gemini/`，判断项目 settings、env、commands、extensions 是否导致问题。
3. 清理 `npx` cache 或卸载当前包管理器安装的 CLI。
4. 重新安装 stable，再用空目录做一次最小启动。
5. 只有确认全局配置本身损坏时，才备份后处理 `~/.gemini`。

这样做的好处是可以保留长期配置和记忆，同时定位问题来源。直接删除全局目录虽然看起来快，但会把 trusted folders、skills、extensions、memory 和团队约定一起抹掉，后续更难判断原始问题。

## 验收方式

卸载后运行 `command -v gemini` 或等价命令确认入口是否还存在。重装后运行 `gemini --version`，再启动一个空目录测试，确认问题是否来自程序包还是旧配置。

## 下一步

<Cards>
  <Card title="Release notes" description="卸载和更新前，先判断版本渠道和已知变更。" href="/docs/gemini-cli/official/08-troubleshooting-reference/83-release-notes" />
  <Card title="安装" description="重装时回到安装页，避免混用多种包管理器。" href="/docs/gemini-cli/official/00-getting-started/01-installation" />
  <Card title="故障排查" description="如果卸载没有解决，回到分层排障而不是继续删除配置。" href="/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting" />
</Cards>

## 官方来源

- [Uninstalling Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/uninstall.md)
