使用 uv 安装本地 .whl 包,最直接的方法是使用 uv pip install 命令并指定文件路径。例如运行 uv pip install ./package-1.0-py3-none-any.whl 即可在当前环境中完成安装。如果希望将包添加到项目的依赖配置中以便后续管理,可以使用 uv add 命令配合 --editable 或 --no-build-isolation 等参数来处理本地文件。

如何直接通过命令行安装单个 whl 文件
直接使用 uv pip install 命令并传入 .whl 文件的相对或绝对路径即可完成安装。该命令会解析 wheel 包中的元数据,将其安装到当前激活的 Python 环境中,并自动处理其声明的依赖项(如果依赖项也已在环境中或可通过索引获取)。

uv pip install ./my_package-1.0.0-py3-none-any.whl
上述命令执行后,uv 会将 my_package 安装到当前虚拟环境或全局环境中。如果该 wheel 包依赖于其他库,而 uv 无法从配置的 PyPI 索引中找到这些依赖,安装可能会失败。此时可以结合 --no-deps 参数跳过依赖检查,仅安装该 wheel 包本身:uv pip install --no-deps ./my_package-1.0.0-py3-none-any.whl。
如何将本地 whl 包集成到项目依赖管理中
在项目管理中,更推荐将本地包作为依赖项加入 pyproject.toml,这样可以通过版本控制或构建流程更好地管理。使用 uv add 命令可以将本地 .whl 文件添加为项目的依赖。
Camoufox 是一个基于 Firefox 构建的开源反检测浏览器,为 Python 自动化工作流程提供强大的指纹注入和反机器人检测规避功能。它与 Playwright 集成,以提供能够绕过现代机器人检测系统的隐身浏览能力。

uv add ./my_package-1.0.0-py3-none-any.whl
执行 uv add 后,uv 会在 pyproject.toml 的 dependencies 或 optional-dependencies 中添加对该本地文件的引用。这通常会将路径转换为 file 协议或直接保留相对路径。这种方式使得团队成员在运行 uv sync 时,能够根据配置文件重新安装所有依赖,包括这个本地包,从而保证环境的一致性。需要注意的是,如果本地包的路径是绝对的,在不同机器上可能失效,建议使用相对路径或将其放入仓库的某个子目录中。
当本地 whl 包存在未满足的依赖时会发生什么
如果在安装本地 .whl 包时,其声明的依赖项在当前环境中不存在且无法从远程索引下载,uv pip install 默认会报错并中止安装。这是因为 uv 遵循标准的 Python 打包规范,确保依赖完整性。用户可以通过 --no-deps 标志强制忽略依赖检查,或者预先手动安装缺失的依赖包。此外,如果本地包之间存在相互依赖,需要按正确的顺序依次安装,或者使用 uv pip install 同时指定多个 .whl 文件,让 uv 尝试解决依赖图。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










