uv 工具管理指南：uvx 与 uv tool install 实战，5 个场景管好 Python 命令行工具
【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv
uv 工具管理指南：带你用 uvx 运行 Python 命令行工具、用 uv tool install 安装常用工具，从 30 秒上手到团队协作、避坑清单，一篇讲全。
先跑起来：30 秒体验 uvx
在终端里直接敲这一行：
uvx pycowsay "hello from uvx"跑完你会看到一只 ASCII 奶牛把这句话叼在嘴边。它没装进你的任何环境：uv 工具管理为每次uvx调用准备一个临时隔离环境，装完即走，系统里不留痕迹。
uvx 还是 uv tool install？
一句话分工：临时用就uvx，常驻用就uv tool install。
| 对比项 | uvx | uv tool install |
|---|---|---|
| 定位 | 临时运行，跑完即弃 | 常驻安装，可执行文件进 PATH |
| 装到哪 | 临时隔离环境 | 每个工具一个独立环境 |
| 能否不带 uv 直接敲命令 | 不能 | 能 |
| 适用场景 | 偶尔用一次、试新版本 | 每天都要用的工具 |
两者共享同一个缓存，所以第一次uvx试过的包，之后uv tool install几乎是秒装。
三分钟上手：安装 uv 并验证
没装过 uv 的话，一行命令搞定（Linux / macOS）：
curl -LsSf https://astral.sh/uv/install.sh | shWindows（PowerShell）则是irm https://astral.sh/uv/install.ps1 | iex。装完验证一下：
uv --version能输出版本号就可以继续了。
uvx 实战：按场景走
uvx 基本运行
工具名直接跟参数就行，工具名后的所有内容都会原样传给工具本身：
uvx black --check main.py注意uvx运行的是命令，不是包。大多数情况下命令名和包名一致，不一致时用--from指定包名，例如uvx --from httpie http。
uvx 指定版本运行工具
@后跟版本号，精确锁版本；范围约束则用--from：
uvx ruff@0.4.0 checkuvx --from "ruff>0.3.0,<0.5.0" ruff check锁定版本后，任何人、任何时间跑同一条命令，行为都完全一致。
用 --with-requirements 给工具注入依赖
有些工具需要额外包配合，比如给 mkdocs 装主题插件。--with可以重复，--with-requirements可以整份 requirements 文件注入：
uvx --with-requirements docs/requirements.txt mkdocs serve注入的包和工具同处一个隔离环境，互不污染。
从 Git 仓库运行
想试主干开发版而不是已发布版本，用--from git+指向仓库，可以带分支或 tag：
uvx --from git+https://github.com/astral-sh/black@main black --help仓库用了 Git LFS 的话，再加--lfs。
uvx 指定 Python 版本
--python决定工具跑在哪个解释器上；本机没有对应版本时，uv 会自动下载：
uvx --python 3.11 pycowsay "hi"uv tool install 实战：把工具变成常驻命令
uv tool install 基本安装
uv tool install ruff装完直接敲ruff --version就能用。注意装进 PATH 的只是可执行文件，包本身的模块依然隔离在工具自己的环境里，python -c "import ruff"会失败——这正是防冲突的关键。
uv tool install 指定版本安装
版本约束直接写进参数，约束会被记住：
uv tool install "ruff>=0.4,<0.5"之后每次升级都不会跳出这个范围。
uv tool install 批量安装
一条命令装多个工具，适合初始化一台新机器：
uv tool install ruff black mypyuv tool upgrade 升级工具
升级是独立的upgrade子命令（别名update）：
uv tool upgrade ruff升级会遵守安装时的版本约束；想突破约束，重新执行一次uv tool install并给出新约束即可。全部工具一起升：
uv tool upgrade --alluv tool uninstall 卸载
按包名卸载，--all清空所有已装工具：
uv tool uninstall ruffuv PATH 配置与 UV_TOOL_BIN_DIR
装完工具如果提示"command not found"，先查可执行文件目录：
uv tool dir --bin最快的修复方式是让 uv 自己写 shell 配置：
uv tool update-shell手动配置的话，Linux / macOS 加到~/.bashrc或~/.zshrc：
export PATH="$HOME/.local/bin:$PATH"Windows（PowerShell）加到用户环境变量：
$env:PATH += ";$env:LOCALAPPDATA\uv\tools\bin"想换默认目录，设置UV_TOOL_BIN_DIR指定可执行文件目录、UV_TOOL_DIR指定工具环境目录，再重新安装即可。
团队协作：锁定版本 + 同步工具清单
Makefile 固定工具版本：把检查命令锁死在指定版本，谁的机器跑make lint结果都一样：
lint: uvx ruff@0.4.0 check .CI 里同样推荐uvx按版本运行，不依赖 CI 镜像里预装的东西：
uvx mypy==1.13.0 src/导出/导入工具清单：uv tool list --show-version-specifiers会列出每个工具及安装时的版本约束，重定向到文件就是团队的工具清单；新机器按清单逐个装回去：
uv tool list --show-version-specifiers > tools.txtxargs -L1 uv tool install < tools.txt避坑清单
症状：安装后提示 command not found。解法：跑uv tool dir --bin确认目录，再执行uv tool update-shell写入 PATH 配置，重开终端。
症状：uvx 报依赖版本冲突。解法：给工具本身或冲突的包指定具体版本（uvx ruff@0.4.0），或用--with注入你认可的版本；确认是缓存问题就加--refresh强制重新解析。
症状：Docker 容器里装完工具找不到命令。解法：ENV里显式写死工具可执行目录的 PATH，别依赖update-shell（容器里没有交互式 shell 配置可写）。
症状：指定版本后提示找不到。解法：@语法只接受精确版本（ruff@0.4.0），范围约束必须走--from "ruff>=0.4"；另确认版本写的是包名而不是命令名。
小结
- 临时用
uvx，常驻用uv tool install，共享缓存所以都快。 - 版本约束写进参数，uv 会一直替你守着。
- PATH 出问题先查
uv tool dir --bin，再用uv tool update-shell修。
现在就去终端敲一条uvx pycowsay "上手成功"，然后把你最常用的工具装起来。
更多工具用法见官方指南 docs/guides/tools.md
【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
