English | 中文说明

Hunyuan3D-2 Windows Portable

A dedicated package for running Hunyuan3D 2.0 Gradio Web App (official demo) on Windows.

Integrated mmgp from Hunyuan3D-2GP made by DeepBeepMeep, allowing models to run on consumer-grade GPUs.

How to Use - Generate Shape Only

This approach creates a 3D mesh (untextured) from a single image, featuring straightforward steps and no extra software dependencies. Beginners please complete this step first before moving on to more advanced usage.

1. Requirements:

   • NVIDIA GPU with at least 6GB of VRAM (4GB may work but will be very slow).

   • GPU driver version must be newer than March 2024 (version >550).

2. Download Hunyuan3D2_WinPortable.7z and extract it to a convenient location.

   • Or check for newer versions at releases page.

3. Run 0-initialize.bat and wait. If updates fail, simply rerun to continue.

4. Run 2-download-models.bat and wait for the download to complete (~19GB).

5. Run 3-start.bat, ignore error messages about EP Error. Wait for the info message:

   Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

6. Open http://localhost:8080/ in your browser. Enjoy!

7. Output files will be saved in Hunyuan3D-2\gradio_cache.

8. You can close the command window to stop the program.

Other options:

• If your GPU has less than 6GB VRAM, use run-very_low_vram.bat.

• If your GPU has 24GB+ VRAM, run run-high_vram.bat for better performance.

How to Use - Generate Shape and Texture

This approach generates both mesh and textures, requiring more VRAM and additional installation steps.

Note	Please complete all steps from the previous section How to Use - Generate Shape Only first, then exit the program before proceeding with the following steps.

1. Requirements:

   • NVIDIA GPU with at least 8GB of VRAM (6GB may work but will be very slow).

   • Minimum 24GB of system RAM.

2. Install CUDA Toolkit 12.8.1.

   • Only Libraries and Compilers are needed to install.

   • Other versions ( 12.6 or 12.4 ) should work as well. You don’t need to install additional if you already have one.

3. Install Visual Studio Build Tools 2022 ( Page | EXE ).

   • During setup, select the "Desktop development with C++" workload.

4. Run 1-compile-install-texture-gen.bat, wait for the installation to finish.

5. Run 3-start.bat. When ready, the following message will appear:

   Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

   • If you see EP Error: Can’t load TensorRT, the app will automatically fallback to CUDA. This error can be safely ignored.

6. Open http://localhost:8080/ in your browser.

7. Output files will be saved in Hunyuan3D-2\gradio_cache as well.

Other options:

• Use run-very_low_vram.bat if your GPU has less than 8GB VRAM.

• Use run-high_vram.bat if your GPU has 24GB+ VRAM.

How to use - Multi View to 3D

This method generates 3D models with textures using 1 to 4 fixed viewpoint images. The official example uses front-back-left views, while users may optionally add the right view for four-viewpoint model generation.

The process offers two working modes:

1. "Gen Shape" (generates untextured mesh)

2. "Gen Textured Shape"

   • Note: The texture generation feature requires the same setup steps described in the previous section "How to Use - Generate Shape and Texture".

If you’ve successfully run texture generation in the previous step, simply:

1. Exit the program

2. Run 4-start-mv.bat

Additional options:

• For GPUs with ≥24GB VRAM: Use run-mv-high_vram.bat for better performance.

How to use - API Server

This method launches a local server to enable API access for external applications (e.g. Blender) to utilize the model’s capabilities.

• Same setup procedure as described in "How to Use - Generate Shape and Texture".

• Run 5-start-api-server.bat and wait for loading.

  • (Optional) To change ports: Modify the --port 8081 parameter in the file.

How to use - Text to 3D

The Text to 3D feature combines: (1) Text to Image (2) Image to 3D. For an experienced user, it might not be worth downloading another Text-to-Image model. Therefore, this feature is disabled by default. However, you can easily enable it:

• After the 2-download-models.bat script completes, run run-with-text_to_3d.bat. This will download the required models (~13.4GB) and start the app. If the download fails, simply re-run the script.

• Texture Generation feature is optional for Text-to-3D. You can always get a white mesh without installing texgen.

By the way, the HunyuanDiT model works great for this purpose.

Tips

1. The "Remove Background" feature uses rembg with default settings, which may leave faint white edges. Turn it off if your images already have clean alpha channels.

2. The VRAM optimization in this package came from DeepBeepMeep's Hunyuan3D-2GP project. For VRAM/RAM requirements of different profile levels, see the mmgp documentation.

   • Very-low VRAM mode: --profile 5

   • Default mode: --profile 4

   • High VRAM mode: --profile 1 (requires 48GB RAM + 24GB VRAM)

3. To update:

   • Run UPDATE.bat.

   • Note: This package uses a customized fork of Hunyuan3D 2.0, and a scripts repo, both maintained by me, which might not always be up-to-date.

4. Need to set a proxy for Internet access?

   • Add the following lines on top to any script you run into issues with, adjusting for your proxy server:

set HTTP_PROXY=http://localhost:1080
set HTTPS_PROXY=http://localhost:1080

Thanks

• Special thanks to the researchers, developers, and all contributors of Hunyuan3D 2.0.

• Kudos to DeepBeepMeep for creating mmgp and Hunyuan3D-2GP, bringing Hunyuan3D 2.0 to less-capable GPUs.

More

Explore my other projects:

• Comfy3D-WinPortable - Run ComfyUI-3D-Pack on Windows.

• StableFast3D-WinPortable - Run SF3D on Windows.

• ComfyUI-Windows-Portable - A ComfyUI bundle with 40+ custom nodes.

• ComfyUI-WinPortable-XPU - A ComfyUI bundle for Intel GPUs.

• ComfyUI-Docker - Run ComfyUI in containers.