Vi3W
Skip to content

Guides

Hunyuan 3D local install: run Hunyuan3D 2.0 and 2.1 on your own GPU

Hunyuan 3D local install guide: Hunyuan3D 2.0 vs 2.1, VRAM requirements, install steps, low-VRAM mode, ComfyUI and the licence's territory rule.

3 min read

A translucent jade dragon forming from glowing particles above an open computer case with a graphics card
Illustration. Hunyuan3D's open models run on your own graphics card.

Quick answer

How do I run Hunyuan 3D locally?

Clone Tencent's Hunyuan3D-2 or Hunyuan3D-2.1 repository, install PyTorch for your CUDA version and the requirements, build the texture renderer extensions, then run gradio_app.py. Hunyuan3D 2.0 needs about 6 GB of VRAM for shape and 16 GB with texture; 2.1 needs 10 GB for shape and 29 GB for both, with a low-VRAM mode.

Which Hunyuan3D to install

From the Hunyuan3D-2 and Hunyuan3D-2.1 READMEs:

  • Hunyuan3D 2.0 (January 2025): 1.1B shape model plus 1.3B texture model. About 6 GB VRAM for shape, 16 GB for shape plus texture.
  • Hunyuan3D 2mini (March 2025): a 0.6B shape model, the lightest option, with Turbo and Fast variants.
  • Hunyuan3D 2mv: takes multiple views (front, side, back).
  • Hunyuan3D 2.1 (June 2025): 3.3B shape model and 2B PBR texture model. 10 GB shape, 21 GB texture, 29 GB both.

Both READMEs say they support macOS, Windows and Linux.

Licence first: the Tencent Hunyuan community licence does not apply in the EU, the UK or South Korea. See open-source 3D AI licences.

Video: The EASIEST Way to Install Hunyuan3D for Free in ComfyUI!, by PixelArtistry (YouTube)

Install Hunyuan3D 2.1 from the repo

  1. Clone the Hunyuan3D-2.1 repository and cd into it.
  2. Install PyTorch. The README pins torch==2.5.1 with CUDA 12.4 wheels (--index-url https://download.pytorch.org/whl/cu124).
  3. Install requirements: pip install -r requirements.txt.
  4. Build the texture extensions: in hy3dpaint/custom_rasterizer run pip install -e ., then build the renderer in hy3dpaint/DifferentiableRenderer as the README describes.
  5. Run the web app: python3 gradio_app.py with the model path options from the README. Add --low_vram_mode on smaller cards.

Weights download from Hugging Face (tencent/Hunyuan3D-2.1) on first run.

Install Hunyuan3D 2.0 or 2mini

Same pattern in the Hunyuan3D-2 repo. Its README shows gradio_app.py commands for 2mini, 2mv and 2.0, each with --low_vram_mode, and Turbo variants with --enable_flashvdm. It also includes api_server.py (--port 8080) for the Blender add-on.

Easier routes

  • ComfyUI with a Hunyuan3D wrapper node pack: Hunyuan 3D in ComfyUI.
  • Windows portable build: a community package linked from the Hunyuan3D-2 README.
  • Hugging Face demo: no install, queues apply.
A jade dragon forming above a computer
Illustration. VRAM decides whether you can run texture as well as shape.

Troubleshooting

  • Out of memory: shape-only, --low_vram_mode, or 2mini.
  • Extension build errors: your CUDA toolkit must match PyTorch's CUDA version.
  • Slow on Mac: expect much longer times than on NVIDIA GPUs. See Hunyuan 3D on Mac.

After generating

Export GLB and import into Blender for scale, retopology and export: Hunyuan 3D to Blender.

Hunyuan without installing

Vi3W runs Hunyuan 3D 2, 2 Mini and 2.1 plus hosted 3.0, 3.1 Fast and 3.1 Pro in the browser with no GPU, next to TRELLIS, Meshy and Tripo, and exports GLB, FBX or OBJ. Use through Vi3W is governed by Vi3W's terms. Try Vi3W.

Frequently asked questions

hunyuan 3d local requirements

From the READMEs: Hunyuan3D 2.0 needs 6 GB of VRAM for shape and 16 GB for shape plus texture. Hunyuan3D 2.1 needs 10 GB for shape, 21 GB for texture and 29 GB for both. Both list macOS, Windows and Linux.

hunyuan 3d 3.1 local

The open, downloadable Hunyuan3D models on Tencent's GitHub are the 2.x family. Check Tencent-Hunyuan's repositories for whether newer versions have been released as open weights; otherwise use them through a hosted service.

hunyuan 3d local install

Follow the repo README, or use ComfyUI with a Hunyuan3D wrapper, or a community Windows portable build linked from the Hunyuan3D-2 README.

Last reviewed