如何卸载 Rust Cargo 全局安装的二进制包

在 Rust 开发生态中，cargo install <crate> 是安装各种高效命令行工具（如 ripgrep、bat、eza、zellij）的标准方式。

然而，随着尝试的工具越来越多，你的全局可执行文件目录可能会堆积很多不再使用的二进制文件。如何安全、干净地卸载它们？

本文将通过直观的图解与实例，带你深入了解 Cargo 管理二进制文件的机制、cargo uninstall 命令的使用技巧以及手动清理方法。

通俗解释 (ELI5)：Cargo 如何管理二进制文件？#

你可以把操作系统的终端环境想象成一个工匠的工具挂板：

• 当你执行 cargo install <crate> 时：Cargo 会下载源码并编译为二进制可执行文件，然后把这把“螺丝刀/扳手”挂到公共工具架 $HOME/.cargo/bin 上。同时，Cargo 会在账本（.crates2.json）上记下一笔：“安装了该 crate 及其包含的工具”。
• 当你执行 cargo uninstall <crate> 时：Cargo 翻开账本，找到属于该 crate 的可执行文件，从工具架 $HOME/.cargo/bin 上取下并删除，最后清空账本中的相应记录。

flowchart TD
    subgraph Install["安装过程 (cargo install)"]
        CRATES_IO["Crates.io / Git 仓库"] -->|下载源码并编译| CARGO_BUILD["Cargo 编译器"]
        CARGO_BUILD -->|复制可执行文件| BIN_DIR["$HOME/.cargo/bin<br>(在系统 PATH 中)"]
        CARGO_BUILD -->|记录元数据| METADATA[".crates2.json<br>(元数据追踪器)"]
    end

    subgraph Uninstall["卸载过程 (cargo uninstall)"]
        CMD["cargo uninstall <crate>"] -->|查阅账本| METADATA
        CMD -->|删除可执行文件| BIN_DIR
        CMD -->|更新并清除元数据| METADATA
    end

1. 查看已安装的二进制包列表#

在决定卸载之前，建议先查看当前系统中通过 Cargo 全局安装了哪些工具。

在终端中运行以下命令：

cargo install --list

输出内容将清晰列出每个已安装 crate 的名称、版本以及它所提供的可执行文件：

bat v0.24.0:
    bat
ripgrep v14.1.0:
    rg
cargo-update v13.3.0:
    cargo-install-update
    cargo-install-update-config

[!NOTE] 请注意：一个 crate 可能会包含多个二进制文件（例如 cargo-update 同时安装了 cargo-install-update 和 cargo-install-update-config）。此外，crate 名称与生成的二进制名称可能不同（例如 ripgrep crate 对应的可执行命令是 rg）。

2. 基础卸载：使用 cargo uninstall#

要卸载已通过 cargo install 安装的包，基本命令格式为：

cargo uninstall <package_name>

实战示例：#

如果你之前安装了 ripgrep 并想将其移除：

cargo uninstall ripgrep

Cargo 的反馈输出示例：

Removing /Users/username/.cargo/bin/rg

系统会立即从 .cargo/bin 目录中删除可执行文件 rg，并同步更新 Cargo 的元数据记录。

3. 进阶命令与常用选项#

3.1. 仅卸载指定的二进制文件 (--bin)#

如果某个 crate 包含多个可执行文件，而你只想移除其中的某一个，可以使用 --bin 参数：

cargo uninstall <package_name> --bin <binary_name>

例如，仅从 cargo-update 中移除 cargo-install-update-config：

cargo uninstall cargo-update --bin cargo-install-update-config

3.2. 从自定义根目录卸载 (--root)#

如果你在安装时使用了 --root 参数指定了非默认路径，卸载时也必须传入对应的路径：

cargo uninstall --root /custom/path <package_name>

4. 手动删除 (Manual Removal)#

当元数据文件损坏或由于特殊原因无法通过 Cargo 命令卸载时，可以直接进入 Cargo 的全局目录手动删除对应的二进制文件。

Cargo 默认安装路径：#

• macOS / Linux: $HOME/.cargo/bin/（或 ~/.cargo/bin/）
• Windows: %USERPROFILE%\.cargo\bin\（例如 C:\Users\用户名\.cargo\bin\）

手动删除命令：#

在 macOS / Linux 系统：

rm ~/.cargo/bin/rg

在 Windows (PowerShell) 系统：

Remove-Item "$HOME\.cargo\bin\rg.exe"

[!WARNING] 手动删除文件虽然会移除可执行程序，但在 .crates2.json 中可能仍会保留记录。cargo install --list 可能仍会显示该 crate，直到元数据被覆盖或清理。

5. 常见问题与排错指南#

常见问题 1: error: no package found with name ...#

当你在卸载命令中误输入了二进制命令名而不是 crate 包名时，就会触发此错误。

• 错误写法: cargo uninstall rg
• 正确写法: cargo uninstall ripgrep

请先运行 cargo install --list 确认准确的 crate 包名。

常见问题 2: 卸载后终端依然可以执行该命令#

如果在执行 cargo uninstall 之后，命令依然能够正常运行，通常由以下两个原因造成：

1. Shell 路径缓存机制: 当前终端会话（Zsh/Bash）在内存中缓存了旧的可执行文件路径。刷新缓存即可解决：
   • Zsh: rehash
   • Bash: hash -r
2. 通过其他包管理器安装过: 该工具可能是通过 Homebrew (brew)、APT、Scoop 等其他工具安装的。使用以下命令定位其实际来源：
   查询命令路径

   which <命令名>

   bash

常用命令速查表#

参考资料#

• The Cargo Book: cargo-uninstall 参考手册 ↗
• The Cargo Book: cargo-install 参考手册 ↗
• Rust 官方文档: Cargo 指南 ↗