如何让 uv 从本地目录查找 Python wheel？

结论

UV_DEFAULT_INDEX 应指向包索引，不能直接指向只存放 .whl 文件的普通目录。对于 $HOME/mypackages/ 这样的本地 wheel 目录，可以在 uvx 命令中使用 --find-links：

uvx --find-links "$HOME/mypackages" --with mypackage python

--find-links 会让 uv 在指定目录中查找可安装的分发包。目录中的 mypackage-1.0.0-py3-none-any.whl 与包名 mypackage 相符，uv 可以据此找到该 wheel。

为什么原配置找不到包

export UV_DEFAULT_INDEX="$HOME/mypackages"

UV_DEFAULT_INDEX 用于设置默认包索引地址。普通目录中的 wheel 文件不具备索引页面结构，因此把目录路径设为默认索引，并不会让 uv 扫描其中的 wheel 文件。依赖解析时，uv 因而会提示找不到 mypackage。

配置方式

每次运行时，都可以通过 --find-links 指定本地目录：

uvx --find-links "$HOME/mypackages" --with mypackage python

如果只想从该本地目录和其他显式指定的来源查找，可以加上 --no-index，让 uv 不使用默认包索引：

uvx --no-index --find-links "$HOME/mypackages" --with mypackage python

使用 --no-index 时，mypackage 所需的依赖也必须能从本地目录或其他显式配置的来源获取。否则，通常保留默认索引更合适。

注意事项

要将本地目录配置为包索引，需要提供符合包索引格式的索引服务或目录结构。目录里只有 wheel 文件时，使用 --find-links 更直接。pip 能从本地文件或目录安装软件包，并不表示该目录也能直接用作 uv 的默认索引。

备注：内容仅供参考。