全局工具管理 uv tool

问题：全局工具的冲突

你想全局装 black（格式化）、mypy（类型检查）、httpie（HTTP CLI）、poetry（别的项目还在用）。直接 pip install --user 很快就会遇到依赖冲突：black 要 click>=8，某老工具要 click<7——装一个坏一个。

正确做法：每个工具一个独立虚拟环境。历史上这是 pipx 的工作。uv 把这个能力内化为 uv tool，速度快 10 倍，配置更少。

uv tool install — 全局安装

# 装一个工具
uv tool install ruff
uv tool install black
uv tool install httpie
uv tool install poetry

# 带 extras 安装
uv tool install "mkdocs[python]"

# 指定 Python 版本
uv tool install --python 3.12 ansible

# 为工具注入额外依赖（很常见：某工具需要额外插件）
uv tool install mkdocs --with mkdocs-material --with mkdocs-minify-plugin
uv tool install poetry --with poetry-plugin-export

安装后：

• 每个工具有独立的 ~/.local/share/uv/tools/<name>/ 环境
• 可执行入口链接到 ~/.local/bin/<name>（需在 PATH 中）
• 升级/卸载/重装互相完全隔离

# 首次使用需要把 ~/.local/bin 加进 PATH
uv tool update-shell   # 自动修改 shell 配置

uvx — 一次性运行工具

uvx 是 uv tool run 的简写。它不永久安装工具，而是在临时环境中运行一次，类似 npx：

# 一次性跑一个你没装过的工具
uvx ruff check .
uvx cowsay "hello uv"
uvx --from httpie http GET https://api.github.com/users/octocat

# 指定版本
uvx ruff@0.6.0 format .
uvx ruff@latest check .

# 带额外依赖
uvx --with pytest-cov pytest

# 指定 Python 版本跑工具
uvx --python 3.12 --from "django==4.2" django-admin startproject mysite

管理已安装的工具

# 列出所有
uv tool list
# - black v24.4.2
#   - black
#   - blackd
# - ruff v0.6.0
#   - ruff

# 升级
uv tool upgrade ruff
uv tool upgrade --all              # 升级所有工具

# 给工具加/减 extras 或 with 依赖
uv tool install --upgrade mkdocs --with mkdocs-awesome-pages-plugin

# 卸载
uv tool uninstall ruff
uv tool uninstall --all

# 查看工具环境详情
uv tool dir             # 工具环境的根目录
uv tool dir --bin       # 可执行文件的目录

常见工具安装清单（推荐）

# Linter / Formatter
uv tool install ruff             # 全家桶 linter + formatter
uv tool install mypy             # 类型检查
uv tool install pyright          # 微软的类型检查（可选）

# 包管理辅助
uv tool install pip-audit        # 依赖漏洞扫描
uv tool install pipdeptree       # 依赖树可视化（uv tree 替代）

# 实用 CLI
uv tool install httpie           # 命令行 HTTP 客户端
uv tool install yt-dlp           # 视频下载
uv tool install cookiecutter     # 模板生成

# Web 开发
uv tool install pre-commit       # Git hook 管理
uv tool install mkdocs --with mkdocs-material  # 文档

# AI / 数据
uv tool install "langchain-cli"
uv tool install marker-pdf       # PDF to markdown

uvx 运行 Git 仓库里的工具

不只是从 PyPI，uvx 也能直接运行 git 仓库：

# 运行别人仓库里的脚本
uvx --from git+https://github.com/user/cool-tool cool-tool

# 指定分支
uvx --from "git+https://github.com/user/cool-tool@dev" cool-tool

# 本地路径（测试自己开发中的工具）
uvx --from ./mytool mytool

工具隔离的好处

从 pipx 迁移

# 查看 pipx 已装的工具
pipx list --short

# 全部迁到 uv tool（简单复制命令即可）
for tool in $(pipx list --short | awk '{print $1}'); do
  uv tool install "$tool"
done

# 卸载 pipx（可选）
pip uninstall pipx

共享 Python 解释器节省磁盘

uv tool 的每个工具环境默认共享 uv 管理的 Python 解释器（通过硬链接），一台机器装 20 个工具不会多出 20 份 Python 二进制，总体磁盘占用很小。

# 查看所有工具环境的实际占用
du -sh ~/.local/share/uv/tools/*