【3D Gen 入坑（1）】Hunyuan3D-Paint 2.1 安装 `custom_rasterizer` 报错完整排查
Hunyuan3D-Paint 2.1 安装 custom_rasterizer 报错完整排查
适用场景：在
hy3dpaint/custom_rasterizer目录执行
pip install .或pip install -e .时出现 Failed building wheel / No module named ‘torch’ / nvcc fatal 等编译错误。
一、问题现象
pip install日志开头正常，但到 Building wheel for custom_rasterizer 阶段报错退出。- 典型报错片段（按出现顺序）
ModuleNotFoundError: No module named 'torch'Your compiler ... is not compatible with the compiler Pytorch was built with/bin/sh: ... g++-11: No such file or directorynvcc fatal : Failed to preprocess host compiler properties.
二、根因分析
-
pip 隔离环境导致缺少 torch
pip install -e .默认会临时创建 “build-isolation” 环境。里面没装 PyTorch，cpp_extension找不到头文件而直接报错。 -
CUDA 12.4 对 GCC 13 不兼容
系统原本只有 gcc-13；nvcc 解析 C 头文件时遇到_Float128类型即失败。 -
nvcc 找不到正确的 host compiler
我们通过 conda 安装了 gcc-11，但默认可执行文件名是
x86_64-conda-linux-gnu-g++（无后缀）。
路径写错就会触发 “No such file or directory”。
三、解决方案总览
| 环节 | 目标 | 命令 / 处理方式 |
|---|---|---|
| 1. 安装匹配的 GCC 11 | 让 nvcc 使用受支持的版本 | conda install -c conda-forge gcc_linux-64=11 gxx_linux-64=11 |
| 2. 指定编译器变量 | nvcc & pip 都用 gcc-11 | bash<br>export CUDAHOSTCXX=$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++<br>export CC=$CUDAHOSTCXX<br>export CXX=$CUDAHOSTCXX<br>export PATH=$CONDA_PREFIX/bin:$PATH<br>hash -r<br> |
| 3. 禁用 build-isolation | 让 pip 直接用当前环境（含 torch） | 普通安装：pip install . --no-build-isolation --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple可编辑： PIP_NO_BUILD_ISOLATION=1 pip install -e . --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple |
| 4. 验证 | 导入 .so 并检查函数 | python<br>import custom_rasterizer_kernel as k<br>print(hasattr(k, "rasterize_image")) # True 即成功<br> |
四、完整操作步骤
下文假设 conda 环境名为
hunyuan21_wenda，CUDA Toolkit 路径/usr/local/cuda-12.4，请按实际情况调整。
1. 准备 conda 环境并安装 GCC-11
conda activate /opt/.../envs/hunyuan21_wenda
conda install -c conda-forge gcc_linux-64=11 gxx_linux-64=11 # 不会覆盖 gcc-13
2. 配置编译器变量
# 让 nvcc & pip 都用 gcc-11
export CUDAHOSTCXX=$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++
export CC=$CUDAHOSTCXX
export CXX=$CUDAHOSTCXX# 确保 conda/bin 在 PATH 最前
export PATH=$CONDA_PREFIX/bin:$PATH
hash -r# 验证
$CUDAHOSTCXX --version # 输出 gcc 11.4.0 即 OK
可将上述
export写入~/.bashrc，以后无需重复设置。
3. 进入源码目录并清理残留
cd /opt/.../Hunyuan3D-2.1/hy3dpaint/custom_rasterizer
pip uninstall -y custom_rasterizer custom_rasterizer_kernel 2>/dev/null
rm -rf build dist *.egg-info
4. 编译安装
方式 A：普通安装（最推荐）
pip install . --no-build-isolation --no-deps \-i https://pypi.tuna.tsinghua.edu.cn/simple
方式 B：可编辑安装
PIP_NO_BUILD_ISOLATION=1 \
pip install -e . --no-deps \-i https://pypi.tuna.tsinghua.edu.cn/simple
成功后日志应包含：
Building wheel for custom_rasterizer (setup.py) ... done
Successfully installed custom_rasterizer-0.1
5. 快速自测
python - <<'PY'
import custom_rasterizer_kernel as k
print("rasterize_image 函数存在？", hasattr(k, "rasterize_image"))
PY
若输出 True 或 rasterize_image 函数存在？ True，编译链全部打通。
五、常见坑与排查清单
| 现象 | 排查点 |
|---|---|
No module named 'torch' | 忘记 --no-build-isolation 或未安装 torch |
Your compiler ... not compatible with the compiler Pytorch was built with | 用的是系统 /usr/bin/g++，未设置 CC/CXX |
/bin/sh: ... g++-11: No such file or directory | 路径写成 g++-11 而实际文件无后缀 |
nvcc fatal : Failed to preprocess host compiler properties | CUDAHOSTCXX 指向不存在的文件或 gcc 版本过高（≥13） |
六、总结
- 编译器三选一：GCC 11 / 12 / 9 均与 CUDA 12.x 兼容，选 11 最省事。
- pip 隔离环境 常导致 “缺包” 问题，开发者插件建议一律加
--no-build-isolation。 - 环境变量
CUDAHOSTCXX决定 nvcc 的 host compiler，必须指向真实可执行文件。 - Hunyuan3D-Paint 2.1 编译通过后即可继续执行
bash run_local.sh ...等下游脚本。
祝大家少踩坑，愉快玩转 Hunyuan3D！