Windows 下使用 uv 安装 pyicu 报错解决全记录：构建失败与 Wheel 安装绕过方案-CSDN博客

(base) (ragflow) PS D:\extracodes\ragflow> uv sync
Resolved 388 packages in 6ms
  x Failed to build `pyicu==2.15`
  |-> The build backend returned an error
  `-> Call to `setuptools.build_meta.build_wheel` failed (exit code: 1)

      [stdout]
      (running 'icu-config --version')
      (running 'pkg-config --modversion icu-i18n')

      [stderr]
      Traceback (most recent call last):
        File "<string>", line 89, in <module>
        File "<frozen os>", line 679, in __getitem__
      KeyError: 'ICU_VERSION'

      During handling of the above exception, another exception occurred:

      Traceback (most recent call last):
        File "<string>", line 92, in <module>
        File "<string>", line 19, in check_output
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 466, in check_output
          return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 548, in run
          with Popen(*popenargs, **kwargs) as process:
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 1026, in __init__
          self._execute_child(args, executable, preexec_fn, close_fds,
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 1538, in _execute_child
          hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      FileNotFoundError: [WinError 2] 系统找不到指定的文件。

      During handling of the above exception, another exception occurred:

      Traceback (most recent call last):
        File "<string>", line 96, in <module>
        File "<string>", line 19, in check_output
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 466, in check_output
          return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 548, in run
          with Popen(*popenargs, **kwargs) as process:
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 1026, in __init__
          self._execute_child(args, executable, preexec_fn, close_fds,
        File "C:\ProgramData\anaconda3\Lib\subprocess.py", line 1538, in _execute_child
          hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      FileNotFoundError: [WinError 2] 系统找不到指定的文件。

      During handling of the above exception, another exception occurred:

      Traceback (most recent call last):
        File "<string>", line 14, in <module>
        File "C:\Users\HW\AppData\Local\uv\cache\builds-v0\.tmpLTIEvz\Lib\site-packages\setuptools\build_meta.py", line 331, in get_requires_for_build_wheel     
          return self._get_build_requires(config_settings, requirements=[])
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\Users\HW\AppData\Local\uv\cache\builds-v0\.tmpLTIEvz\Lib\site-packages\setuptools\build_meta.py", line 301, in _get_build_requires
          self.run_setup()
        File "C:\Users\HW\AppData\Local\uv\cache\builds-v0\.tmpLTIEvz\Lib\site-packages\setuptools\build_meta.py", line 317, in run_setup
          exec(code, locals())
        File "<string>", line 99, in <module>
      RuntimeError:
      Please install pkg-config on your system or set the ICU_VERSION environment
      variable to the version of ICU you have installed.


      hint: This usually indicates a problem with the package or the build environment.
  help: `pyicu` (v2.15) was included because `ragflow` (v0.18.0) depends on `pyicu`

🚀Windows 下使用 uv 安装 pyicu 报错解决全记录：构建失败与 Wheel 安装绕过方案

在使用 uv 作为 Python 包管理器替代 pip 时，很多用户可能会遇到如下构建错误，尤其是在 Windows 系统中安装 pyicu 时：

error: command 'cl.exe' failed with exit code 2
fatal error C1083: 无法打开包括文件: “unicode/utypes.h”: No such file or directory

这篇文章将记录我在 Windows 下通过 uv 安装依赖包时，遇到 pyicu 构建失败的全过程，并最终找到一个无需构建、绕过失败、成功安装的方案 —— 直接安装预编译的 .whl 包。

❗问题背景

在项目中使用 uv sync 安装依赖时，报如下错误：

x Failed to build `pyicu==2.15`
`-> Call to `setuptools.build_meta.build_wheel` failed (exit code: 1)
fatal error C1083: 无法打开包括文件: “unicode/utypes.h”: No such file or directory

从日志中可以看到，pyicu 依赖 ICU 的 C++ 头文件，而 Windows 下默认没有这些文件。即便安装了 Visual Studio Build Tools，也会因为缺失 unicode/utypes.h 报错。

🔧常见的尝试方案（不推荐）

方法一：设置 ICU_VERSION 环境变量

$env:ICU_VERSION="73.1"

配合 uv sync，大概率仍然失败，因为依赖的 unicode 头文件根本没有。

方法二：使用 `--no-build`

uv sync --no-build

这个方法虽然避免构建 pyicu，但如果 pyicu 在仓库中没有对应的预编译 .whl 文件，也会直接失败（例如另一个包 datrie 也可能失败）：

error: Distribution `datrie==0.8.2` can't be installed because it is marked as `--no-build` but has no binary distribution

方法三：手动构建 ICU + 配置 include/lib 路径

即使你下载并配置好了 ICU SDK，包括：

set INCLUDE=C:\icu\include;%INCLUDE%
set LIB=C:\icu\lib;%LIB%

还是容易失败，因为需要自己处理多个子模块依赖、路径配置、字符集选项等，成本极高，不建议普通用户尝试。

✅推荐方案：使用预编译 Wheel 文件手动安装

第一步：下载 pyicu 的 .whl 包

从可信源下载 Windows 对应 Python 版本的 .whl 文件。例如：

选择与你的 Python 版本相匹配的文件，例如：

pyicu-2.15-cp311-cp311-win_amd64.whl

表示支持 Python 3.11，64 位系统。

第二步：安装 Wheel 包

pip install .\pyicu-2.15-cp311-cp311-win_amd64.whl

输出类似于：

Successfully installed pyicu-2.15

验证是否安装成功：

pip show pyicu

第三步：让 uv 跳过重新构建 pyicu（隐式生效）

此时再次执行：

uv sync

如果仍提示构建 pyicu，建议将其从 pyproject.toml 中移除，或确认安装在当前环境的 site-packages 中，以确保被 uv 正确识别。

🧪 验证导入

import icu
print(icu.ICU_VERSION)

若能成功输出 ICU 版本号，说明安装成功并可正常使用。

💡总结

在 Windows 中使用 uv 安装带有 C 扩展依赖的包（如 pyicu）可能会因构建环境不足报错。最简单可靠的方式是：

从可信源下载 .whl 文件；
使用 pip install 手动安装；
然后再执行 uv sync，跳过该包的构建过程。

这种方式通用适用于所有无法构建的依赖包，可极大降低 Windows 用户的使用门槛。

📌附：检查已安装位置和版本

pip show pyicu

import icu
print(icu.__file__)
print(icu.ICU_VERSION)