ComfyUI-Hunyuan3d-2-1
ComfyUI Wrapper for a/Hunyuan3D v2.1 - From Images to High-Fidelity 3D Assets with Production-Ready PBR Material
Nodes (26)
Six cameras, one rig — and you control every angle with a comma-separated string
The only node in this pack that gets you a file you can actually use
From bare mesh to painted GLB
Read the fine print before you trust it
Load an image in ComfyUI without throwing away its alpha channel
Texturing someone else's mesh — the node that lets you skip generation entirely
Turn a whole folder of photos into 3D meshes with Hunyuan 3D 2.1
One image in, a 3D shape's latent out
The same generator, but the model arrives as a path
The kitchen-sink decimator — every knob meshlib has, and you only need two
The boring-but-necessary step before any texture can stick to your mesh
Let the pack fetch its own weights
The generator that saves its homework — views on disk, ready to upscale later
The cleanup crew — turn the decoder's raw triangle soup into something usable
The quiet utility that keeps your view sizes consistent — and stops bakes from breaking
The decimator that doesn't ask 20 questions — just pick a target and go
The bypass — feed the bake node views you already have, without re-running the generator
Resume a texturing job from disk — the node that remembers the whole camera rig for you
17 scary knobs you can safely ignore
Where the latents stop being math and finally become a mesh
Not the VAE you're used to — this one turns latents into actual geometry
Where the six painted views stop being views and become one texture
The bake node that remembers — it'll even notice when you upscaled your views
The LOD factory — bake a whole chain of low-poly versions in one run
The seam-killer — this is where the texture stops looking stitched
The texturing engine — paint your mesh from a single image, six angles at a time
🌀 ComfyUI Wrapper for Hunyuan3D-2.1
ComfyUI integration for Tencent's powerful Hunyuan3D-2.1 model. Supports textured 3D generation with optional high-quality UV mapping.
📦 Repository & Models
- GitHub: Tencent-Hunyuan/Hunyuan3D-2.1
- Model Weights (HuggingFace): 👉 Main page
🔧 Required Checkpoints
Place the following checkpoints into the corresponding folders under your ComfyUI directory:
ComfyUI/
├── models/
│ ├── diffusion_models/
│ │ └── hunyuan3d-dit-v2-1.ckpt
│ ├── vae/
│ │ └── hunyuan3d-vae-v2-1.ckpt
⚙️ Installation Guide
Tested on Windows 11 with Python 3.12 and Torch >= 2.6.0 + cu126. Compatible with the latest ComfyUI Portable release.
1. Install Python Dependencies
For a standard Python environment:
python -m pip install -r ComfyUI/custom_nodes/ComfyUI-Hunyuan3DWrapper/requirements.txt
For ComfyUI Portable:
python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3d-2-1\requirements.txt
2. Install or Compile Texture Generation Modules
Two critical C++ extensions need to be installed: the custom rasterizer and the differentiable renderer.
Option A: Use Precompiled Wheels (Recommended)
Custom Rasterizer
You will find precompiled wheels in hy3dpain\custom_rasterizer\dist folder
For standard Python:
Example, if you are on Python 3.12:
pip install custom_rasterizer-0.1-cp312-cp312-win_amd64.whl
For ComfyUI Portable:
python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3d-2-1\hy3dpaint\custom_rasterizer\dist\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl
Differentiable Renderer
You will find precompiled wheels in hy3dpaint\DifferentiableRenderer\dist folder
For standard Python:
Example, if you are on Python 3.12:
pip install mesh_inpaint_processor-0.0.0-cp312-cp312-win_amd64.whl.whl
For ComfyUI Portable:
python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3d-2-1\hy3dpaint\DifferentiableRenderer\dist\mesh_inpaint_processor-0.0.0-cp312-cp312-win_amd64.whl.whl
Option B: Manual Compilation (for advanced users)
# Compile custom rasterizer
cd ComfyUI/custom_nodes/ComfyUI-Hunyuan3d-2-1/hy3dpaint/custom_rasterizer
python setup.py install
# Compile differentiable renderer
cd ../DifferentiableRenderer
python setup.py install
🩻 Optional: Fix UV Wrapping for High Poly Meshes (Patched Xatlas)
This upgrade improves UV unwrapping stability for complex meshes.
# Step 1: Uninstall existing xatlas
python_embeded\python.exe -m pip uninstall xatlas
# Step 2: Clone updated xatlas-python wrapper
cd ComfyUI_windows_portable
git clone --recursive https://github.com/mworchel/xatlas-python.git
# Step 3: Replace internal xatlas source
cd xatlas-python\extern
del /s /q xatlas
git clone --recursive https://github.com/jpcy/xatlas
# Step 4: Patch source file
# In xatlas-python/extern/xatlas/source/xatlas/xatlas.cpp:
Line 6774: change `#if 0` → `//#if 0`
Line 6778: change `#endif` → `//#endif`
# Step 5: Install patched xatlas wrapper
cd ../../..
python_embeded\python.exe -m pip install .\xatlas-python\
python_embeded\python.exe -m pip uninstall -y xatlas; `
cd ComfyUI_windows_portable; `
if (Test-Path xatlas-python) { Remove-Item xatlas-python -Recurse -Force }; `
git clone --recursive https://github.com/mworchel/xatlas-python.git; `
cd xatlas-python\extern; `
if (Test-Path xatlas) { Remove-Item xatlas -Recurse -Force }; `
git clone --recursive https://github.com/jpcy/xatlas; `
(Get-Content .\xatlas\source\xatlas\xatlas.cpp) -replace '#if 0', '//#if 0' -replace '#endif', '//#endif' | Set-Content .\xatlas\source\xatlas\xatlas.cpp; `
cd ..\..\..; `
python_embeded\python.exe -m pip install .\xatlas-python\
📂 Directory Overview
ComfyUI/
├── custom_nodes/
│ └── ComfyUI-Hunyuan3d-2-1/
│ ├── hy3dpaint/
│ │ ├── custom_rasterizer/ # Custom rasterizer module
│ │ │ ├── setup.py
│ │ │ └── dist/ # Precompiled wheels
│ │ ├── DifferentiableRenderer/ # Differentiable renderer
│ │ │ ├── setup.py
│ │ │ └── dist/ # Precompiled wheels
├── models/
│ ├── diffusion_models/
│ │ └── [hunyuan3d-dit-v2-1.ckpt](https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-dit-v2-1)
│ └── vae/
│ └── [hunyuan3d-vae-v2-1.ckpt](https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-vae-v2-1)
├── xatlas-python/ # Patched UV unwrapper (optional)
│ └── extern/
│ └── xatlas/
🙏 Acknowledgements
- kijai — Original wrapper developer for Hunyuan3D v2.0
- TrueMike, Agee, Palindar, and the vibrant Discord community
- Tencent team for the incredible Hunyuan3D-2.1 model