Hunyuan3D-2 Image to 3D

Before you install anything: the pack's own README opens with "Don't use this one any more. Hunyuan-3D v2 is built into ComfyUI. Find it in the templates section." That's the author, niknah, telling you his wrapper has been superseded by core ComfyUI's built-in template. Worth taking seriously - but this node still shows up in searches and still does something the built-in path doesn't hand you as easily: point it at any Hunyuan3D checkpoint on Hugging Face, including v2.0, v2.1, multi-view, mini, and turbo, all through one node. So here's what it does and how to run it, official recommendation noted.

What it is and why you'd reach for it

Hunyuan3D2ImageTo3D takes a single 2D image and generates a textured 3D mesh from it - a .glb file you can drop straight into Blender, Unreal, or a game engine. It wraps Tencent's Hunyuan3D-2 and Hunyuan3D-2.1 models - Tencent Hunyuan's 3D line, which the community reads as basically uncontested ground, since Alibaba has nothing comparable and 3D is where Tencent actually leads. The workflow it slots into: generate or find a concept image, cut out the background, feed it in here, get a mesh, clean it up in your 3D tool of choice.

How it works

Under the hood it's a diffusion process over 3D shape (and optionally texture) space, conditioned on your input image, run through whichever Hunyuan3D checkpoint you've pointed it at. Shape generation and texture painting are two separate stages internally - this single node can do both, but painting is the expensive half.

The inputs and outputs that matter

The one thing you must give it is image - and it needs a transparent background. Not optional: without alpha, you'll get a flat square panel back instead of a mesh, because the node has no idea where the subject ends. If your image came out of a background-removal node with an inverted mask, there's an "Invert Mask" node for that. An optional mask input lets you supply that alpha separately if your image doesn't already carry it.

Past that, the knobs a beginner will actually touch:

• steps (default 30) - more steps, more shape fidelity, slower.
• floater_remover, face_remover, face_reducer (all default true) - mesh cleanup passes. Leave these on; Hunyuan3D is known for generating messy, overly dense geometry on organic shapes, and these three exist specifically to fix that before it hits your output file.
• paint (default false) - generates the texture, not just the shape. The node's own tooltip is blunt about it: "Paint needs a lot more VRAM." Leave it off until you know your card can take it.
• model - the Hugging Face ID of the checkpoint, e.g. tencent/Hunyuan3D-2/hunyuan3d-dit-v2-0 or the fp16 fast variant. Right-click → convert to input if you want to swap it via a string node.

The single output is model file, a string path to the .glb written into your output folder - that's the whole deliverable, ready to import elsewhere.

How to install it

Through ComfyUI Manager: search "ComfyUI Hunyuan-3D-2" and install - the recommended path, since Manager handles updates for you. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/niknah/ComfyUI-Hunyuan-3D-2
pip install -r requirements.txt
cd ComfyUI-Hunyuan-3D-2
git submodule update --init

That last line matters - the pack vendors Tencent's own Hunyuan3D-2 and Hunyuan3D-2.1 repos as git submodules, and an older git that mishandles submodules leaves the install half-broken. If that happens, rm -rf Hunyuan3D-2 Hunyuan3D-2.1 and clone them straight from Tencent-Hunyuan yourself.

First run downloads the model weights into ~/.cache/huggingface/hub - a genuinely long wait. Watch the panel button top-right for progress rather than assuming it's hung.

Common issues & troubleshooting

It fails right after you install it. The README calls this out directly: this node can fail on the first restart after install. Just restart ComfyUI again.

Painting doesn't work, or looks bad. For v2.1, the README says painting is currently broken outright, and you need to manually download a RealESRGAN weight into the ckpt folder (wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P ckpt) before it'll even attempt texturing. Even working, community consensus is that Hunyuan3D's paint models are mediocre - expect flat, low-fidelity textures you'll want to touch up in Blender or Substance rather than trust as-is.

Square, flat output instead of a mesh. Your input image doesn't have a real transparent background. Fix the alpha (or feed a proper mask) before this node ever sees it.

Build errors on install. custom_rastizer, hy3dgen, and mesh_processor are compiled Python extensions, and platform quirks are common: Windows needs the Visual C++ Build Tools (portable-Python builds are missing headers entirely - see the pack's issue #3); Ubuntu needs sudo apt install python3-dev libgl-dev; openSUSE needs g++-13 specifically, since its default g++-14+ won't compile it. Precompiled .whl files are on the releases page if you'd rather skip building from source.