彻底卸载 Gemini CLI：npx、npm、Homebrew、MacPorts 四种安装方式对应的清理方法

本文基于 Gemini CLI 仓库官方卸载文档 docs/resources/uninstall.md，完整覆盖 npx 缓存清理、npm 全局卸载、Homebrew 卸载、MacPorts 卸载四种方式的具体命令，并结合仓库中的 package.json、安装指南 与 发布验证流程 补充了安装包结构、卸载后的验证方法和用户数据残留的处置建议。读完后你可以准确地判断自己的安装方式、执行对应的卸载命令，并确认系统中没有残留。

第一步：确认你是怎么安装/运行的

卸载方法取决于当初如何运行 CLI。仓库的 安装指南 提供了五种安装/运行途径：npm 全局安装、Homebrew、MacPorts、Anaconda（本质仍是环境内的 npm 全局安装）、以及免安装的 npx 直接运行。先用以下命令确认当前 gemini 命令来自哪里：

# macOS / Linux
which gemini

# 查看 npm 全局是否安装了 gemini-cli
npm ls -g @google/gemini-cli

# 查看 Homebrew 是否安装了 gemini-cli
brew list gemini-cli

从 package.json 可以确认两个关键事实，它们决定了卸载时要清理的对象：

• 发布包名为 @google/gemini-cli，入口命令通过 bin 字段映射为 gemini，指向 bundle/gemini.js（package.json）。也就是说无论哪种 npm 系安装，最终都会注册一个全局 gemini 可执行文件，卸载的目标就是这个包及它的 bin 链接；
• 运行时要求 Node.js >= 20.0.0（package.json），卸载本身不依赖该版本，但排查问题时的环境应与之一致。

方法一：清理 npx 临时缓存

如果你从没用安装命令、只是用 npx @google/gemini-cli 直接运行过（参见 安装指南 的 npx 方式），CLI 并没有被"安装"到系统中，而是被 npx 缓存在 npm 缓存目录下的 _npx 文件夹里。因此"卸载"的实际动作是清空这个缓存目录，这会同时删除所有曾经用 npx 运行过的包，不只是 gemini-cli。

先定位你的 npm 缓存路径：

npm config get cache

macOS / Linux（缓存路径通常是 ~/.npm/_npx）：

# 路径通常为 ~/.npm/_npx
rm -rf "$(npm config get cache)/_npx"

Windows（PowerShell）（缓存路径通常是 $env:LocalAppData\npm-cache\_npx）：

# 路径通常为 $env:LocalAppData\npm-cache\_npx
Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force

注意 rm -rf 和 Remove-Item -Recurse -Force 都是不可恢复的删除操作，执行前请确认路径正确。如果之后还会用 npx 运行 gemini-cli，缓存会在下次运行时自动重建。

方法二：npm 全局安装的卸载

如果你执行过 npm install -g @google/gemini-cli（或其 @latest、@preview、@nightly 标签变体），用 npm uninstall 加 -g 标志即可：

npm uninstall -g @google/gemini-cli

该命令会把包从全局 node_modules 中完全移除，并注销 gemini 命令链接。仓库 package.json 中声明的平台相关 optionalDependencies（如 @github/keytar、node-pty 及各平台二进制）都随主包一起安装，npm 卸载时会自动一并清理，无需手动处理。

两个补充场景：

• 同时存在本地安装：如果在项目目录里执行过不带 -g 的 npm install @google/gemini-cli，需要在对应项目目录下再执行一次 npm uninstall @google/gemini-cli。仓库的 发布验证流程 就给出了这种组合操作的实际例子（用于发布后本地冒烟测试，文档中明确标注该步骤会破坏本地安装）：

  npm uninstall @google/gemini-cli && npm uninstall -g @google/gemini-cli && npm cache clean --force && npm install @google/gemini-cli@<version>
  

  其中 npm cache clean --force 用于彻底清空 npm 下载缓存——当怀疑安装缓存了损坏或过期的包文件时，这是标准的排查手段。

• 从源码链接过本地版本：如果你在克隆的仓库里执行过 npm link packages/cli 来模拟全局安装（见 安装指南），全局 gemini 指向的是本地开发目录而非 npm 包，此时应先在仓库目录下执行 npm unlink packages/cli（或全局 npm unlink -g @google/gemini-cli）解除链接，再做常规卸载。

方法三：Homebrew 安装的卸载

如果最初是通过 brew install gemini-cli 安装的，用 Homebrew 对应命令移除：

brew uninstall gemini-cli

Homebrew 会将二进制文件安装在 Cellar 与 /opt/homebrew/bin（Apple Silicon）或 /usr/local/bin（Intel）下，brew uninstall 会处理全部这些产物。

方法四：MacPorts 安装的卸载

如果最初是通过 sudo port install gemini-cli 安装的，对应卸载命令是：

sudo port uninstall gemini-cli

卸载后如何验证清理干净

执行完对应方法后，建议做三项检查确认没有残留：

# 1. 确认命令已不可用（macOS/Linux）；应提示 command not found
which gemini

# 2. 确认 npm 全局包已移除；应输出空或 (empty)
npm ls -g @google/gemini-cli

# 3. 确认 Homebrew 中无此软件包（brew 系用户）
brew list gemini-cli

如果 which gemini 仍然指向某个路径，常见原因是 shell 的哈希缓存——执行 hash -r（Bash/Zsh）后重试；若指向某个项目目录，则说明存在本地安装或 npm link 残留，按方法二中的对应步骤处理。

关于用户数据目录的说明

官方卸载文档只针对程序本体，未涉及用户数据。从源码测试代码可以确认，Gemini CLI 的全局配置与扩展数据存放在用户主目录的 ~/.gemini 下（多个测试用例将 getGlobalGeminiDir mock 为 /mock/.gemini 并将扩展目录指向 ~/.gemini/extensions，见 extension-manager-scope 测试）。这意味着：

• 卸载程序不会删除 ~/.gemini 中的认证凭据、设置、会话记录和已安装扩展，重新安装后可继续无缝使用；
• 如果你希望完全清除，在确认不再需要这些数据后，可手动删除主目录下的 .gemini 目录；
• 已安装的扩展、技能等属于应用层内容，其正常移除方式是 CLI 内部的 gemini extensions uninstall <name...> 与 gemini skills uninstall <name>（参见 扩展参考 与 技能文档），这些命令作用于 ~/.gemini 下的数据而非程序本体。

四种方法速查

运行/安装方式	对应命令	影响范围
npx @google/gemini-cli	rm -rf "$(npm config get cache)/_npx"（macOS/Linux）；Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force（PowerShell）	清空所有 npx 缓存包
npm install -g @google/gemini-cli	npm uninstall -g @google/gemini-cli	仅移除该全局包及 gemini 命令
brew install gemini-cli	brew uninstall gemini-cli	仅移除 Homebrew 安装的软件包
sudo port install gemini-cli	sudo port uninstall gemini-cli	仅移除 MacPorts 安装的软件包

无论使用哪种方式，~/.gemini 用户数据目录默认保留，可按需手动清理；对 npm 系安装，卸载前若存在不带 -g 的本地安装或 npm link 链接，记得按上文补充场景一并处理。