Set Up Hunyuan3D-2 on Windows: Complete 2026 Guide (2.0, 2.1 & WinPortable)

Last updated April 2026 — refreshed for current model/tool versions.

Hunyuan3D-2 has evolved rapidly since its January 2025 debut: there are now three active model lines (2.0, 2.1, and the 2.5 research preview), a mature Windows portable package, and first-class ComfyUI support. This guide covers the fastest path to a working Windows installation, which installation approach fits your GPU, and what has changed since the original setup articles were written.

What changed in 2025–2026 (read this if you set it up before)Hunyuan3D-2.1 (June 2025) — fully open-source release including training code, VAE encoder, and a new PBR texture pipeline (diffuse, metallic, roughness, and normal maps). Shape model is 3.3 B parameters; paint model is 2 B parameters. VRAM requirement for the full pipeline jumped to ~29 GB on the official repo.Hunyuan3D 2.5 (June 2025 technical report) — geometric resolution up from 512 to 1024, CLIP score 0.821 vs. 0.809 in v2.0, generation in 8–20 seconds on an RTX 4090. Not yet fully open-sourced as of April 2026; use 2.1 for local runs.WinPortable now targets CUDA 12.9 / driver ≥576.57 — the old driver >550 (March 2024) requirement is the floor. The August 2025 WinPortable release ships two variants: CUDA 12.9 (Blackwell, Ada Lovelace, Ampere, Turing) and CUDA 12.6 (adds Volta, Pascal, Maxwell support).Hunyuan3D-2GP — a community fork that uses MMGP offloading to run shape generation on GPUs with as little as 6 GB VRAM. Profiles 4–5 keep peak VRAM under 6 GB.Official Blender addon — released January 2025. Generates 3D assets directly inside Blender 4.x via a local API server.RTX 20-series not supported in recent builds — Turing is technically compatible but performance is marginal; Ampere (RTX 30-series) or newer is the practical minimum.

Want the full picture? Read our continuously-updated self-hosting LLMs complete guide — hardware sizing, quantization, Ollama vs llama.cpp vs vLLM, and production deployment patterns.

TL;DR: Which installation path should I use?

What is Hunyuan3D-2?

Hunyuan3D-2 is Tencent's open-source system for converting 2D images (and text prompts) into high-resolution 3D assets. It uses a two-stage diffusion architecture: a flow-based DiT model (Hunyuan3D-DiT) generates geometry, and a paint model (Hunyuan3D-Paint) applies texture. The January 2025 release (v2.0) shipped inference code and pre-trained weights; Hunyuan3D-2.1 (June 2025) added full training code and a physically-based rendering (PBR) texture pipeline.

The model family also includes a 0.6 B parameter mini variant (Hunyuan3D-2mini) for fast geometry previews, and a multi-view shape model (Hunyuan3D-2mv) that accepts inputs from multiple camera angles. For teams that need custom 3D asset pipelines at scale, Codersera's vetted AI engineers can integrate Hunyuan3D into production workflows.

System Requirements (April 2026)

Hardware

• Operating System: Windows 10 (64-bit) or Windows 11
• GPU: NVIDIA RTX 30-series (Ampere) or newer strongly recommended; RTX 20-series (Turing) is compatible in WinPortable CUDA 12.6 but slow. AMD GPUs are not officially supported — an unofficial fork exists but is experimental.
• GPU Driver: ≥576.57 (released June 2025). The old ≥550 floor still works but you will miss driver-level optimizations. Update via GeForce Experience or the NVIDIA driver archive.
• VRAM:
  • Shape generation only: 6 GB minimum (3 GB with WinPortable low-VRAM mode)
  • Texture generation: 8 GB minimum, 16 GB recommended
  • Full pipeline (shape + texture, Hunyuan3D-2.1 official): ~29 GB (use WinPortable or 2GP for consumer GPUs)
• RAM: 24 GB minimum (the less VRAM you have, the more RAM is used for model offloading). 32 GB recommended.
• CPU: Any modern multi-core x86-64 processor. Generation is GPU-bound; CPU speed has minimal impact.
• Storage: 60–80 GB free (models are ~26 GB; additional space for dependencies, outputs, and temp files). Install to a path shorter than 200 characters — Windows MAX_PATH issues affect nested pip operations.

Software (for manual installation path)

• Python 3.10 (recommended) — Hunyuan3D-2.1 specifies Python 3.10 + PyTorch 2.5.1+cu124
• CUDA Toolkit 12.4 or 12.9 (only needed if compiling the custom rasterizer)
• Visual Studio Build Tools 2022 with "Desktop development with C++" workload
• Git for Windows

Option A: WinPortable (Recommended for Most Users)

The YanWenKun/Hunyuan3D-2-WinPortable project packages Hunyuan3D 2.0/2.1 with pre-compiled Python wheels and model download scripts for Windows. No Visual Studio or CUDA toolkit installation required for geometry generation (texture compilation is optional).

Step 1: Download the Archive

Go to the Releases page and download the two-part archive for your GPU generation:

• CUDA 12.9 — for RTX 50, 40, 30, and 20-series (Blackwell, Ada Lovelace, Ampere, Turing)
• CUDA 12.6 — for GTX 10-series through RTX 20-series (Volta, Pascal, Maxwell also supported)

After downloading both 001 and 002 files, place them in the same folder and extract with 7-Zip (opens the 001 file; 7-Zip handles multi-part automatically).

Install to a short path such as C:\AI\HY3D2. Paths exceeding 260 characters cause silent pip failures on Windows.

Step 2: (Optional) Enable Developer Mode for Symlinks

Open Settings → System → For developers → Developer Mode and toggle it on. This allows Python to create symbolic links, so model weights are not duplicated when switching between 2.0 and 2.1.

Step 3: Download Models

Inside the extracted folder, double-click 2-download-models.bat (or the equivalent script for 2.1). This downloads approximately 26 GB of model weights from Hugging Face. Expect 20–60 minutes depending on connection speed.

Step 4: Run

Double-click 3-run.bat. The Gradio web interface will start and be accessible at:

http://127.0.0.1:8080/

If you see an "EP Error" in the console on first launch, it can be safely ignored — it indicates a fallback to CUDA inference rather than an alternate execution provider.

Low-VRAM Variants

WinPortable ships several run scripts for constrained hardware:

• run-very_low_vram.bat — for 4–6 GB VRAM (shape generation, slow)
• run-low_vram.bat — for 6–8 GB VRAM
• 3-run.bat (standard) — 8 GB+ VRAM

Option B: Manual Installation (Hunyuan3D-2 or 2.1)

Use this path if you want the latest official codebase, plan to fine-tune, or need the full PBR pipeline from Hunyuan3D-2.1.

Step 1: Install Python 3.10

Download Python 3.10 from python.org. During installation, check "Add Python to PATH". Verify:

python --version
# Expected: Python 3.10.x

Note: Python 3.11+ works with Hunyuan3D-2.0 but the 2.1 official docs specify 3.10.

Step 2: Install Visual Studio Build Tools 2022

Download from visualstudio.microsoft.com and select the "Desktop development with C++" workload. This is required to compile the custom rasterizer used by the texture pipeline.

Step 3: Install CUDA Toolkit (for texture compilation)

Download CUDA Toolkit 12.4 or 12.9 from developer.nvidia.com. Confirm your driver is ≥576.57 before installing. Verify:

nvcc --version

Step 4: Clone the Repository

git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git
cd Hunyuan3D-2

For Hunyuan3D-2.1 (PBR pipeline):

git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
cd Hunyuan3D-2.1

Step 5: Create a Virtual Environment

python -m venv venv
venv\Scripts\activate

Step 6: Install PyTorch with CUDA 12.4

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

Install PyTorch before running requirements.txt to avoid version conflicts on Windows.

Step 7: Install Python Dependencies

pip install -r requirements.txt
pip install -e .

Step 8: Compile Texture Components (Optional)

Shape generation works without this step. For texture generation:

# Navigate to the custom rasterizer directory
cd hy3dgen/texgen/custom_rasterizer    # Hunyuan3D-2.0
# or
cd hy3dpaint/custom_rasterizer         # Hunyuan3D-2.1

python setup.py install
cd ../../..

For Hunyuan3D-2.1, also compile the differentiable renderer:

bash hy3dpaint/DifferentiableRenderer/compile_mesh_painter.sh

On Windows, use Git Bash or WSL2 for the bash command above.

Step 9: Download Model Weights

Models are available on Hugging Face. The download script handles authentication automatically:

python download_weights.py

Alternatively, run the provided batch script:

.\2-download-models.bat

Model sizes:

• Hunyuan3D-2 (v2.0): ~26 GB total
• Hunyuan3D-2.1 Shape (3.3 B params): ~14 GB
• Hunyuan3D-2.1 Paint (2 B params): ~8 GB
• Hunyuan3D-2mini (0.6 B params): ~3 GB

Step 10: Run the Interface

python app.py

Open http://127.0.0.1:8080/ in your browser.

Option C: Hunyuan3D-2GP (GPU-Poor Version)

The community fork deepbeepmeep/Hunyuan3D-2GP integrates MMGP (advanced model offloading) to run shape generation on 4–6 GB VRAM. Quality is identical to the original — only the memory management layer differs.

Profile Selector

Edit the profile in the run script or pass it as an argument. Profiles 4–5 require more system RAM (32–48 GB) because model layers are offloaded to CPU.

Option D: ComfyUI Workflow

ComfyUI natively supports Hunyuan3D-2mv (geometry). For the full pipeline including texture synthesis, install the ComfyUI-Hunyuan3DWrapper node by Kijai. It supports CUDA 12.4/12.6 and Windows Python 3.12 environments with PyTorch 2.6.0.

For a thorough walkthrough of running other local AI agents and models alongside Hunyuan3D, see the OpenClaw + Ollama setup guide for running local AI agents, which covers environment isolation, model management, and GPU scheduling for multi-model workflows.

To install the wrapper node inside ComfyUI Manager, search for ComfyUI-Hunyuan3DWrapper. Model weights should be placed in ComfyUI/models/Hunyuan3D/.

Option E: Official Blender Addon

Tencent released blender_addon.py on January 27, 2025. It connects to a running local Hunyuan3D API server and generates 3D assets directly inside Blender 4.x. Parameters exposed in the UI include octree resolution (128–512) and guidance scale (1.0–10.0).

1. Start a local API server: python app.py --server-mode
2. Download blender_addon.py from the GitHub repo.
3. In Blender: Edit → Preferences → Add-ons → Install from Disk, select the file.
4. Configure the API server address in the addon settings.

For Hunyuan3D 2.5, the community Hunyuan3DBlenderBridge addon adds direct integration with automatic mesh conversion for animation topologies.

Performance and Benchmarks

Generation Speed (Real Hardware)

Quality Benchmarks (v2.0 vs v2.5)

Hunyuan3D 2.5 remains a research preview; local inference uses Hunyuan3D-2.1.

Troubleshooting Common Issues

EP Error on Launch

You see EP Error: ONNX provider not found or similar. This is expected on most Windows setups — the model falls back to the CUDA execution provider automatically. Generation will still work normally.

Insufficient VRAM / CUDA Out of Memory

• Switch to run-very_low_vram.bat (WinPortable) or Profile 4–5 (2GP).
• Close other GPU-intensive applications.
• Reduce the octree resolution parameter (lower values = less VRAM).
• If using 2.1 and the full pipeline fails, run shape and texture generation as separate steps.

CUDA / Driver Version Mismatch

PyTorch checks the driver version at import time. If you see CUDA driver version is insufficient, update your NVIDIA driver to ≥576.57. You do not need to reinstall the CUDA Toolkit — WinPortable bundles the required runtime libraries.

Path Too Long (Windows)

If pip install fails with FileNotFoundError or Access is denied in a deeply nested path, move the entire installation to a shallower directory such as C:\AI\HY3D2. Windows has a 260-character path limit unless Developer Mode symlinks are enabled.

Custom Rasterizer Compilation Fails

• Confirm Visual Studio Build Tools 2022 is installed with the C++ workload.
• Run the compilation from a Developer Command Prompt (not a regular PowerShell).
• Ensure CUDA Toolkit bin directory is in your PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\bin.
• The setup.py includes a /bigobj flag to prevent "bigobj" compilation errors; if you forked the repo verify this flag is present.

Texture Inconsistency / Blurry Details

Fine-detail patterns (fabric, text, logos) may appear blurry if the source image lacks resolution. Use a high-resolution input (at least 1024×1024) and increase the texture upscaler strength. The 2.1 PBR pipeline produces more accurate material detail than the RGB-based 2.0 paint model.

Generated Mesh Too Dense for Games

Hunyuan3D can produce meshes with 300,000–600,000 triangles for complex subjects. For real-time game assets, run the output through a decimation tool in Blender or use the Instant Meshes remesher. Alternatively, use a lower octree resolution for faster, simpler meshes.

How to Choose Your Workflow

• Just want to try it quickly → WinPortable, CUDA 12.9 variant, default run script.
• RTX 20-series or older Nvidia → WinPortable CUDA 12.6 variant.
• Only 4–6 GB VRAM → Hunyuan3D-2GP with Profile 4.
• Blender artist → install Blender addon + run local API server; use 2.0 for compatibility.
• Node-based workflow user → ComfyUI + ComfyUI-Hunyuan3DWrapper.
• Researcher or fine-tuner → manual install of Hunyuan3D-2.1 with full training code.
• AMD GPU → no official support; check the experimental AMD fork, accept instability.

FAQ

What GPU is the minimum to run Hunyuan3D-2 on Windows?

An NVIDIA GPU with 6 GB VRAM running a driver ≥576.57 will run shape generation via WinPortable. For texture synthesis you need at least 8 GB VRAM, and realistically 12 GB for a usable speed. RTX 30-series (Ampere) or newer is the practical minimum; older Turing GPUs work with the CUDA 12.6 WinPortable variant but are slow.

Do I need to install the CUDA Toolkit separately?

Not for WinPortable — it bundles the required CUDA runtime. You only need the full CUDA Toolkit (12.4 or 12.9) if you are compiling the custom rasterizer for texture generation in the manual install path, or if you plan to extend the code.

What is the difference between Hunyuan3D-2.0 and 2.1?

2.0 uses an RGB-based paint model for textures. 2.1 (June 2025) replaces this with a PBR pipeline that generates physically-accurate diffuse, metallic, roughness, and normal maps — resulting in more realistic light interaction and material properties. 2.1 also ships with full training code. VRAM requirements are higher for the 2.1 paint model.

What is Hunyuan3D 2.5? Can I run it locally?

2.5 is a research preview announced via technical report in June 2025 (arXiv 2506.16504). It raises geometric resolution to 1024 and achieves a CLIP score of 0.821. As of April 2026, full local inference weights have not been released separately; use Hunyuan3D-2.1 for local runs.

Can I use Hunyuan3D-2 without an internet connection after setup?

Yes. Once models are downloaded to disk, the Gradio interface and inference code run fully offline. Set HF_DATASETS_OFFLINE=1 and TRANSFORMERS_OFFLINE=1 in your environment to prevent timeout errors from Hugging Face checks.

Is there a cloud or API option instead of local?

Yes. Tencent's Hunyuan3D-Studio provides a hosted version. Community APIs are also available on platforms like Replicate and fal.ai. Cloud inference avoids local VRAM constraints but incurs per-generation cost.

How do I export models for use in game engines?

The Gradio interface exports to .glb (GLB/GLTF) format by default, which is directly importable into Unity, Unreal Engine, Godot, and Blender. For production game assets, decimate the mesh first (Blender's Decimate modifier or Instant Meshes) to reduce triangle count for real-time rendering.

Does Hunyuan3D-2 support text-to-3D, or only image-to-3D?

Both. You can pass a text prompt directly, and the system internally generates a reference image via a linked image generation model before producing the 3D asset. Image-to-3D tends to produce more predictable results for specific subjects; text-to-3D is better for quick concept generation.

References & Further Reading

• Tencent-Hunyuan/Hunyuan3D-2 — Official GitHub Repository
• Tencent-Hunyuan/Hunyuan3D-2.1 — PBR Pipeline, Full Open-Source Release
• arXiv 2501.12202 — Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation
• arXiv 2506.16504 — Hunyuan3D 2.5: Towards High-Fidelity 3D Assets Generation with Ultimate Details
• YanWenKun/Hunyuan3D-2-WinPortable — Windows Portable Package (CUDA 12.6/12.9)
• deepbeepmeep/Hunyuan3D-2GP — GPU-Poor MMGP Offloading Fork
• tencent/Hunyuan3D-2 on Hugging Face — Model Card and Weights
• ComfyUI Wiki — Complete Hunyuan3D 2.0 ComfyUI Workflow Guide