Install Hunyuan3D 2.1: 3D Generation AI Setup Guide

Which version do you actually install, and why does the texture step keep breaking? Two questions, one guide. This covers Hunyuan3D 2.1 – released by Tencent on June 13, 2025 as the first production-ready 3D asset generation model with PBR materials.

Two parts to this install: Python deps (easy) and two CUDA-compiled modules (where most setups break). The compiled modules are what every guide skips past with a one-liner.

Pick your install path first

Three real paths exist. Pick wrong and you’ll waste a couple of hours.

The rest of this article covers the official source install on Linux/Windows – it’s what the docs target and what fine-tuning requires. Windows user who just wants to generate? Jump to the WinPortable section below.

System requirements (actual numbers)

• GPU: NVIDIA, CUDA-compatible. ≥3 GB VRAM for geometry on the optimized 2.1 model; ≥6 GB VRAM for texture generation (per the WinPortable README, which documents the 2.1 minimums in detail)
• System RAM: ≥24 GB – see the note below on why this floor matters
• Driver: NVIDIA ≥576.57, released June 2025 or later
• Python: 3.10, with PyTorch 2.5.1+cu124 – as of June 2025, these are the versions Tencent tested against
• OS: macOS, Windows, or Linux
• Disk: Allow generous free space for model weights and the Hugging Face cache combined; the download on first run is substantial

The 24 GB RAM figure isn’t a soft recommendation. The less VRAM you have, the more system RAM mmgp offloading consumes – it’s a direct inverse relationship. A 6 GB card offloads far more than a 16 GB card does. That’s why the WinPortable docs list 24 GB as a floor, not a target.

Think of it like swap space on disk. When a process outgrows physical RAM, the OS pages to disk and everything slows – but it doesn’t crash. The same principle applies here: insufficient system RAM doesn’t cause a clean error, it causes a stall that looks like a hang.

Install from source

Open a fresh conda or venv environment with Python 3.10 first. Mixing this into an existing environment almost always produces a silent PyTorch version conflict later.

# Clone the repo
git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
cd Hunyuan3D-2.1

# Install PyTorch - exact versions matter
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 
 --index-url https://download.pytorch.org/whl/cu124

# Python dependencies
pip install -r requirements.txt

# Compile the custom rasterizer (this is where things break)
cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..

# Compile the differentiable renderer
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

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

The two compile steps are where this diverges from a standard pip install. Turns out the rasterizer and differentiable renderer are custom CUDA extensions – pip can report a clean exit even when the actual nvcc compilation quietly errored. The only reliable check is inspecting the output directory after the fact, not trusting pip’s return code.

First run and the VRAM flag

The README launch command is correct, but most consumer GPUs need one extra flag:

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

--low_vram_mode activates offloading so a card meeting the 6 GB texture threshold can actually finish a texture pass. Without it, cards below that threshold will run out of memory mid-generation – the official README includes this flag but buries it; almost no tutorial highlights it.

First launch: model weights download from Hugging Face automatically. Set HF_HOME to a drive with space before running, or the download may fail partway through in your home directory.

Verify it works

Gradio binds to http://127.0.0.1:7860. Upload a PNG with a clear subject, click generate. Watch both stages complete without the terminal going silent.

Shape preview appears but texture hangs with no terminal output? The rasterizer didn’t compile correctly – pip’s clean exit was a false positive. Check hy3dpaint/custom_rasterizer/lib/: empty means the build failed.

Common install errors

These come from real community reports via the DeepWiki troubleshooting reference and the WinPortable README, not generic PATH advice.

1. PyTorch CUDA version mismatch. Make sure CUDA 12.4+ is installed. If you had a previous torch install in the same environment, it silently wins – fresh venv is the fix, not reinstalling torch on top.

2. Custom rasterizer compilation fails.which nvcc must return a path on Linux. On Windows you need Visual Studio Build Tools 2022 with the “Desktop development with C++” workload – that’s a separate install from VS Code, and it must happen before pip tries to compile.

3. compile_mesh_painter.sh permission denied. Run chmod +x compile_mesh_painter.sh first. One line, but easy to miss when following the README quickly.

4. “nvcc not found” on Mac. No fix. Apple Silicon has no CUDA. The Codersera Mac guide documents this: the rasterizer fails silently, texture generation doesn’t run, and you get untextured mesh output only. That’s the Mac ceiling.

5. Long-path errors on Windows. Clone to a shallow path like C:AIHY3D2. Nested pip dependencies push past the 260-character MAX_PATH limit surprisingly fast – the WinPortable README flags this explicitly.

6. Driver too old. Anything below driver 576.57 (pre-June 2025) will fail in non-obvious ways under current PyTorch builds. Update before starting.

One thing worth knowing: errors 2 and 4 have the same symptom – shape works, texture silently hangs. The distinguishing factor is your OS. Mac? It’s error 4, unfixable. Linux/Windows? It’s error 2, fixable with build tools.

Upgrading, downgrading, or removing it

Hunyuan3D 2.1 isn’t a drop-in over 2.0. The repos are separate (Hunyuan3D-2 vs Hunyuan3D-2.1) and the texture pipeline is architecturally different: 2.0 used an RGB-based paint model; 2.1 replaces it with a PBR pipeline that produces diffuse, metallic, roughness, and normal maps. You clone fresh – there’s no migration path.

Removal: delete the cloned directory, delete your virtual environment, delete the Hugging Face cache (~/.cache/huggingface on Linux/Mac). No registry entries, no system-wide hooks. It’s gone.

If you don’t want to compile anything

The WinPortable build by YanWenKun is a Windows-specific package for Hunyuan3D 2.0 and 2.1 that integrates mmgp offloading for consumer GPUs. The August 2025 release (v4-cu129) ships Hunyuan3D-2.1 support, Blackwell (RTX 50 series) compatibility, a GUI launcher, Python 3.12.11, CUDA 12.9, and PyTorch 2.8.0 – no compilation step.

The trade-off is real: you can’t fine-tune from a portable build, and you’re tied to the package maintainer’s update schedule. For generation-only workflows, though, it’s a legitimate choice – not a shortcut.

For the architecture and PBR pipeline internals, the Hunyuan3D 2.1 technical report (arXiv 2506.15442) covers the design decisions behind the two-stage DiT + Paint approach in detail.

FAQ

Can I run Hunyuan3D 2.1 without a GPU?

No. The diffusion transformer requires CUDA – CPU inference isn’t supported.

Why does shape generation work but texture generation fail silently?

Start here: check hy3dpaint/custom_rasterizer/lib/. Empty directory means the rasterizer build failed even though pip said it succeeded. Re-run with pip install -v -e . and read the nvcc output – you’ll see the actual error. On Linux the usual culprit is nvcc not on PATH; on Windows, missing Visual Studio Build Tools. Mac users: this is the Mac ceiling described in error 4 above, not a fixable configuration issue.

WinPortable or source install – which should I use?

Depends on what you’re doing. WinPortable works out of the box on Windows, handles VRAM offloading automatically, and supports the latest Blackwell GPUs as of the August 2025 release. Source install gives you access to fine-tuning and full control over the environment – but you’re signing up for the rasterizer compile step and dependency management. If you’re generating assets and not training, WinPortable is the pragmatic call. If you’re experimenting with the model itself, build from source.

Start here: clone the repo, build a Python 3.10 venv, run the install commands in order. The rasterizer compile output is the only step that needs your full attention – everything else either works or fails loudly.