Hunyuan3D 2.1 in ComfyUI: Local 3D Generation, VRAM and the Licence Catch

Hunyuan3D 2.1 is Tencent’s open-weight image-to-3D system. You give it one picture of an object and it returns a mesh, then a second model paints physically based (PBR) textures onto that mesh. Tencent released it on 13 June 2025, and it is still the newest Hunyuan3D shape model whose weights you can download.

This guide covers what the two models are, which files to download and how big they really are, the memory Tencent states for each stage, how far ComfyUI’s native nodes go, the smaller 2mini and 2mv models, and the licence, which is stricter than most image-model licences in two ways that matter. BFWR has not run Hunyuan3D. Everything here comes from Tencent’s README, code and licence, ComfyUI’s documentation and source, and the published model files.

Quick answer

• Two stages: a shape model (the README calls it 3.3B) builds an untextured mesh, and a 2B paint model adds albedo, metallic and roughness maps.
• Memory, per Tencent: 10 GB for shape, 21 GB for texture, 29 GB for both in one run.
• ComfyUI: the native template makes the untextured mesh only, from one 7.37 GB file. Textures need a custom node pack, and those ship pre-built wheels for Windows with NVIDIA CUDA only.
• Smaller GPUs: Hunyuan3D-2mini (0.6B shape model) and 2mv (multi-view) are the older 2.0 family, with Tencent quoting 6 GB for 2.0 shape generation.
• Licence: no rights at all in the EU, the UK or South Korea, and that covers the generated meshes too. Companies above 1 million monthly active users on the release date need Tencent’s permission, a threshold 100 times lower than HunyuanVideo 1.5’s.

What Hunyuan3D 2.1 is

As in Hunyuan3D 2.0, shape and texture are separate models. The 2.1 change is in texture: the README says the “upgraded PBR pipeline leverages physics-grounded material simulation” in place of the earlier RGB texture model. Tencent’s Gradio app writes the result as an OBJ with an albedo map plus separate metallic and roughness maps, and converts it to GLB.

• Shape (Hunyuan3D-Shape-v2-1): a flow-matching diffusion transformer. Its config.yaml lists 21 layers at a hidden size of 2,048, six of them mixture-of-experts layers with 8 experts and 2 active, conditioned on a DINOv2 image encoder. The tensor header of ComfyUI’s single-file copy gives 3.05B parameters for the transformer, 0.33B for the shape VAE and 0.30B for the image encoder, all FP16. The README lists 3.3B.
• Texture (Hunyuan3D-Paint-v2-1): a multi-view diffusion model the README sizes at 2B. Its configs describe a Stable Diffusion 2-style UNet with a CLIP image encoder and a text encoder whose config names stabilityai/stable-diffusion-2. It generates several views of the object at once, conditioned on your mesh: Tencent’s code example sets 6 views at 512 pixels, and the Gradio app 8 views at 768.

Files and their real sizes

Sizes are read from the Hugging Face file listings on 1 November 2026, where GB means a billion bytes.

The whole tencent/Hunyuan3D-2.1 repository is 14.91 GB. Tencent’s shape, VAE and paint UNet weights are .ckpt and .bin files, which are Python pickles, and Tencent’s Gradio app loads the shape model with use_safetensors=False. The Comfy-Org repack, now at Comfy-Org/Hunyuan-3D-2.1, is safetensors.

ComfyUI’s template library also lists the 2.1 template’s download as 4,939,212,390 bytes, which is the size of the 2.0 checkpoint. The file it actually downloads is 7,365,943,290 bytes, and ComfyUI’s tutorial gives “about 7.4 GB”.

How much VRAM it needs

Tencent’s 2.1 README states it in one line: “It takes 10 GB VRAM for shape generation, 21GB for texture generation and 29GB for shape and texture generation in total.” For comparison, the Hunyuan3D 2.0 README says “It takes 6 GB VRAM for shape generation and 16 GB for shape and texture generation in total.”

So a 12GB card runs the 2.1 shape stage, texturing needs 24GB, and both stages in one process need 32GB. Texture, not shape, sets the hardware.

Tencent’s Gradio app has a --low_vram_mode flag, but in the 2.1 code its only effect is a call to torch.cuda.empty_cache() after each generation; the line that would offload the paint model to the CPU is commented out.

Running it in ComfyUI

Native nodes: shape only

ComfyUI supports Hunyuan3D in core. Its source registers three model types (Hunyuan3Dv2, Hunyuan3Dv2_1 and Hunyuan3Dv2mini), and the template library has an official “HY 3D 2.1: Single View to Model” template. Its description says it produces “a raw white-mesh geometry without textures or materials”. ComfyUI’s tutorial says the same of all its Hunyuan3D workflows: “Like the other workflows on this page, it outputs an untextured mesh.”

To use it, update ComfyUI, open the template (or search “HY 3D 2.1” in the template browser), and put the checkpoint here:

ComfyUI/
└── models/
    └── checkpoints/
        └── hunyuan_3d_v2.1.safetensors

The template’s settings, read from its JSON:

Remove the background from your input image first; ComfyUI’s tutorial points to custom nodes for that.

Textures: custom node packs

Textures need a community pack. Tencent’s README lists visualbruno/ComfyUI-Hunyuan3d-2-1 first in its community section, and ComfyUI’s tutorial links kijai/ComfyUI-Hunyuan3DWrapper and ComfyUI-3D-Pack. Repository health, read from the GitHub API on 1 November 2026:

The texture stage needs two compiled extensions, a custom rasterizer and a differentiable renderer. Tencent’s rasterizer is built as a CUDAExtension with a .cu kernel, so it needs an NVIDIA GPU and toolchain. Both packs ship pre-built wheels only for Windows with Python 3.12 and CUDA 12.x. kijai’s README says “For the texturegen part compilation is needed”, and if no wheel suits your system you compile them yourself. visualbruno’s pack loads Tencent’s .ckpt files into models/diffusion_models/ and models/vae/.

The cloud nodes are a different product

Seven of the eleven Hunyuan3D entries in ComfyUI’s 3D template group are API templates that run on Tencent’s servers. ComfyUI’s Tencent API nodes offer model versions 3.0 and 3.1, carry a price badge and need a Comfy account. They return textured GLB and OBJ files, but your image leaves your machine, and they are not the open weights this guide is about.

Smaller GPUs: 2mini and 2mv

The smaller options are Hunyuan3D 2.0 models from March 2025:

• Hunyuan3D-2mini “contains a 0.6B shape generator”, per its model card. The FP16 safetensors file is 3.82 GB, because it also carries a 1.14B-parameter image encoder and a 0.21B VAE. Its Turbo and Fast variants are the same size. ComfyUI’s tutorial says “The Hunyuan3D-2mini model requires only 5GB VRAM”; Tencent states no separate figure for it.
• Hunyuan3D-2mv is fine-tuned from Hunyuan3D-2 “to support multiview controlled shape generation”: you feed front, left, back and right views. Each variant is 4.93 GB. ComfyUI has official templates for 2mv and 2mv-turbo.

Both produce shape only. For textures, Tencent’s commands pair them with the 2.0 paint model, which brings you back to the 16 GB total Tencent states for 2.0.

Mac and AMD

The README says “Hunyuan3D 2.1 supports Macos, Windows, Linux”, but the next section says “We test our model with Python 3.10 and PyTorch 2.5.1+cu124”, and the texture rasterizer is CUDA code. Issue #32, “How does Hunyuan3D-2.1 support MacOS?”, has been open since June 2025, and a pull request adding MPS support has been open since April 2026. The Gradio app accepts mps as a device. Tencent documents no Mac setup, and the texture stage depends on CUDA code, so as published, texturing on a Mac is not supported. Tencent makes no statement about AMD or ROCm.

The licence catch

Hugging Face shows license:other. The text is the Tencent Hunyuan 3D 2.1 Community License Agreement; 2mini and 2mv use the matching 2.0 agreement, with the same key terms. What follows is a reading of the published text, not legal advice.

• No rights in three territories. The first line reads “THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA”. The grant covers “the worldwide territory” excluding those three.
• The outputs are covered too. Section 5(c): “You must not use, reproduce, modify, distribute, or display the Tencent Hunyuan 3D 2.1 Works, Output or results of the Tencent Hunyuan 3D 2.1 Works outside the Territory.” As written, a generated mesh displayed or distributed in the EU, UK or South Korea falls outside the licence. How that applies to, say, a game sold worldwide is a question for a lawyer.
• Otherwise you own your outputs. “Tencent claims no rights in Outputs You generate.” There is no non-commercial clause.
• A low user threshold. If your products had more than 1 million monthly active users “in the preceding calendar month” on the release date (13 June 2025), you must ask Tencent for a licence. HunyuanVideo 1.5’s licence sets the same test at “greater than 100 million monthly active users”. As written, the test is taken at the release date, not later.
• No training other models. Section 5(b): “You must not use the Tencent Hunyuan 3D 2.1 Works or any Output or results of the Tencent Hunyuan 3D 2.1 Works to improve any other AI model”. Generated meshes cannot become training data for a non-Hunyuan model.
• A new disclosure rule. A Section 3(e) added on 17 October 2025 says that if you deploy the model to serve third parties, you must name the real provider, and “You shall expressly and conspicuously state that Tencent is not affiliated with, associated with, sponsoring, or endorsing any such service, product, or functionality.” It speaks of deploying the Works, which the licence defines separately from Outputs.
• Distribution duties. Pass on the licence, mark changed files, and ship a Notice file with Tencent’s wording. The acceptable use policy also asks you to label machine-generated content placed in public.

All three model cards carry the metadata flag extra_gated_eu_disallowed: true, but the repositories are not gated, and Hugging Face’s documentation says “This feature will only activate if your model is already gated.” The download works from the EU; that does not license you there.

Our ComfyUI video generation guide covers HunyuanVideo’s version of the same territory clause.

Running Tencent’s own app safely

Outside ComfyUI, Tencent’s README installs the requirements, compiles the two texture extensions and starts a Gradio app (Linux or Windows with an NVIDIA GPU):

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt

python3 gradio_app.py \
  --model_path tencent/Hunyuan3D-2.1 \
  --subfolder hunyuan3d-dit-v2-1 \
  --texgen_model_path tencent/Hunyuan3D-2.1 \
  --low_vram_mode

Both gradio_app.py and api_server.py default to --host 0.0.0.0, exposing them to your network; add --host 127.0.0.1. The API server has no authentication and allows cross-origin requests from any site (allow_origins=["*"]). And requirements.txt adds two extra package indexes, Tencent’s and Aliyun’s PyPI mirrors, so pip may fetch packages from them.

Is it still maintained, and what came after

The Tencent-Hunyuan/Hunyuan3D-2.1 repository has no tagged releases and is not archived. Its last commit was the licence update of 17 October 2025, with none in the 90 days to 1 November 2026, and 160 issues and pull requests are open.

The Hunyuan3D 2.0 README links a technical report for Hunyuan3D 2.5 (June 2025), and ComfyUI’s API nodes offer 3.0 and 3.1. No weights for any of the three appear on Tencent’s Hugging Face or GitHub accounts as of 1 November 2026. The later open releases are add-ons: Hunyuan3D-Omni, whose card says it “inherits the structure of Hunyuan3D 2.1” and adds point cloud, voxel, skeleton and bounding-box control, and Hunyuan3D-Part for splitting a mesh into parts. Both appeared in September 2025.

FAQ

Can ComfyUI make textured models with Hunyuan3D 2.1?

Not with core nodes, which make an untextured mesh. Textures need a custom node pack such as visualbruno’s, compiled CUDA extensions and, by Tencent’s figure, a 24GB card.

What GPU do I need for Hunyuan3D 2.1?

Tencent states 10 GB for shape, 21 GB for texture and 29 GB for both together. A 12GB card handles shape only; texturing needs 24GB.

Can I use Hunyuan3D 2.1 in the EU or the UK?

The licence grants no rights there, and section 5(c) extends that to the generated meshes. The files download from the EU, but that does not license you.

Can I sell 3D models made with Hunyuan3D 2.1?

Inside the licensed territory the text claims no rights in outputs and has no non-commercial clause, subject to the 1 million user threshold and the acceptable use policy. Selling into the EU, UK or South Korea is where it bites.

Related guides and tools

• ComfyUI templates: which run locally and which need the cloud
• How to run Stable Diffusion locally
• Best local image generation models in 2026
• Local AI video generation in ComfyUI
• AI upscale models, including Real-ESRGAN
• ComfyUI models and VRAM
• Image model directory

Sources

• Tencent-Hunyuan/Hunyuan3D-2.1 on GitHub (README, LICENSE, gradio_app.py, api_server.py, requirements.txt)
• tencent/Hunyuan3D-2.1, tencent/Hunyuan3D-2mini and tencent/Hunyuan3D-2mv on Hugging Face (cards, configs, file listings)
• Tencent-Hunyuan/Hunyuan3D-2 README (2.0 VRAM figures, model list)
• Comfy-Org/Hunyuan-3D-2.1 (repackaged checkpoint)
• ComfyUI: Hunyuan3D 2.0 and 2.1 tutorial, the workflow_templates index and the ComfyUI source (comfy/supported_models.py, comfy_api_nodes/nodes_hunyuan3d.py)
• visualbruno/ComfyUI-Hunyuan3d-2-1 and kijai/ComfyUI-Hunyuan3DWrapper
• HunyuanVideo 1.5 licence (user threshold comparison)
• Hugging Face: gated models and tencent/Hunyuan3D-Omni

Updated 1 November 2026. File sizes, parameter counts from the safetensors headers, repository activity, ComfyUI templates and licence texts were read on that date.