Executive Installation Guide - ComfyUI with Hunyuan3D 2.1

Executive Installation Guide

ComfyUI with Hunyuan3D 2.1 - For Non-Technical Users

Purpose: This guide will install a complete AI-powered 3D generation system (ComfyUI + Hunyuan3D 2.1) on a fresh Windows machine with minimal user interaction.

What This Software Does

ComfyUI with Hunyuan3D 2.1 is an AI system that:

Converts images into 3D models
Generates professional PBR textures (used in architecture, games, film)
Exports models in industry-standard formats (GLB, OBJ)
Runs locally on your computer (no cloud/subscription needed)

Business Value

Rapid 3D prototyping from concept images
Architectural visualization asset creation
Integration with Blender, Unreal Engine, other 3D software

System Requirements

Hardware:

Windows 10 or Windows 11 (64-bit)
NVIDIA GPU with at least 12GB VRAM (RTX 3090/4090 recommended)
16GB+ system RAM (32GB recommended)
100GB free disk space (50GB for models, 50GB for software)

Software Prerequisites (to be installed):

None initially - this guide covers everything from scratch

Installation Overview

This installation has TWO PHASES:

PHASE 1: Foundation Software (Manual Installation) ~1 hour

These are industry-standard tools that require one-time setup:

Miniconda - Python environment manager (10 minutes)
CUDA Toolkit 12.8 - NVIDIA GPU computing platform (15 minutes + restart)
Visual Studio 2022 Build Tools - Microsoft C++ compiler (20 minutes)
Git for Windows - Version control system (5 minutes)

PHASE 2: ComfyUI + Hunyuan3D (Automated Script) ~30-45 min

Everything else is automated by a single Python script:

Creates isolated Python environment
Downloads and installs ComfyUI
Installs Hunyuan3D extension with all dependencies
Compiles custom GPU acceleration code
Verifies installation
Creates desktop shortcut

PHASE 1: Foundation Software Installation

Step 1: Install Miniconda (Python Environment Manager)

What it does: Manages different Python versions without conflicts

Installation:

In the bundle_setup-files folder you extracted, navigate to: 1_Installers/
Double-click Miniconda3-latest-Windows-x86_64.exe
Installation wizard:
- Click "Next" → "I Agree"
- IMPORTANT: Select "Just Me (recommended)"
- IMPORTANT: Check "Add installation to my PATH environment variable" ✓
- IMPORTANT: Check "Register Miniconda3 as my default Python 3.13" ✓
- Click "Install" (wait ~2 minutes)
- Click "Finish"

Screenshot: Miniconda installer showing "Add to PATH" checkbox (CHECKED)

This is the most critical checkbox - must be checked for installation to succeed!

CRITICAL VERIFICATION:

Open Command Prompt (search "cmd" in Start menu)
Type: python --version
Should show: Python 3.x.x (with Miniconda in the path)
If you get "python is not recognized":
- You MUST uninstall and reinstall Miniconda
- This time CHECK the "Add to PATH" checkbox during installation
- The automated installer WILL FAIL without this!

Also verify conda:

In the same Command Prompt, type: conda --version
Should show: conda 24.x.x (or similar)
If command not found, restart Command Prompt and try again

Screenshot: Command Prompt showing "python --version" output successfully

Example: "Python 3.11.x" confirms PATH is configured correctly

⛔ STOP & CHECK: Do NOT proceed to Step 2 until both python --version and conda --version work correctly!

Step 2: Install CUDA Toolkit 12.8 (NVIDIA GPU Computing)

What it does: Enables GPU acceleration for AI models (CRITICAL for performance)

Installation:

In bundle_setup-files/1_Installers/, double-click cuda_12.8.0_windows_10.exe
Installer starts:
- IMPORTANT: Choose "Custom (Advanced)" installation (NOT Express!)
- Click "Next"
Select components to install:
- UNCHECK ALL except:
- ✓ CUDA Toolkit 12.8 (check this box - this is what we need)
- UNCHECK: CUDA Driver (may conflict with your existing drivers)
- UNCHECK: GeForce Experience / NVIDIA App (unnecessary bloat)
- UNCHECK: Visual Studio Integration (we don't need this)
- Click "Next"
Accept default installation location, click "Next"
- Wait 10-15 minutes for installation
- Click "Close" when complete

Screenshot: CUDA installer showing "Custom (Advanced)" selected and component selection screen

Show ONLY "CUDA Toolkit 12.8" checked, all others unchecked (Driver, GeForce Experience, etc.)

⚠️ CRITICAL: Restart your computer after CUDA installation

Step 3: Install Visual Studio 2022 Build Tools (C++ Compiler)

What it does: Compiles custom GPU acceleration code for Hunyuan3D

Installation:

In bundle_setup-files/1_Installers/, double-click vs_BuildTools.exe
Installer starts:
- Installer will download components (~5GB)

CRITICAL STEP 1 - Select Workload:

In the installer window, find the "Workloads" tab (should be selected by default)
Check the box: "Desktop development with C++"

CRITICAL STEP 2 - Select Individual Components:

Click the "Individual Components" tab (next to Workloads tab at top)
You'll see a search bar at the TOP of the Individual Components tab
For each component below, copy the entire name and paste into the search bar, then check the box:

MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)
Windows 11 SDK (10.0.26100.6901)
C++ CMake tools for Windows
Testing tools core features - Build Tools
C++ AddressSanitizer
vcpkg package manager
C++ ATL for latest v143 build tools (x86 & x64)
C++ MFC for latest v143 build tools (x86 & x64)

How to use the search bar:

Copy a component name (e.g., MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest))
Paste into search bar at top
Check the box next to the result
Clear search bar and repeat for next component

Screenshot: VS Build Tools - Individual Components tab with search bar at top

Show the search bar and one component being searched/checked (e.g., "MSVC v143")

Start Installation:
- Click "Install" (wait 15-20 minutes)
- Click "Close" when complete

Verify installation:

Open Command Prompt
Type: dir "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat"
Should show file found (not "File Not Found")

Step 4: Install Git for Windows (Version Control)

What it does: Downloads code repositories (required for ComfyUI installation)

Installation:

In bundle_setup-files/1_Installers/, double-click Git-x.xx.x-64-bit.exe
Installer starts:
- Click "Next" through most options (defaults are fine)
- IMPORTANT: When you see "Adjusting your PATH environment"
  - Select: "Git from the command line and also from 3rd-party software"
- IMPORTANT: When you see "Configuring the line ending conversions"
  - Select: "Checkout as-is, commit as-is"
- Continue clicking "Next" → "Install"
- Click "Finish"

Configure Git for long paths (CRITICAL for ComfyUI):

Open Command Prompt
Type: git config --global core.longpaths true
Press Enter (no output is normal)

Screenshot: Command Prompt showing "git config --global core.longpaths true" command

This command has no output - just shows the next prompt line (normal behavior)

Step 5: Enable Long Paths in Windows (CRITICAL)

What it does: Allows Windows to handle long file paths (required for Python packages)

Steps:

In bundle_setup-files/2_Registry_And_Verification/, double-click enable_long_paths.reg
Click "Yes" to UAC prompt
Click "Yes" to registry edit confirmation
Click "OK" when done

⚠️ CRITICAL: Restart your computer after enabling long paths

PHASE 1 COMPLETE - VERIFICATION

After restarting from Step 5:

In bundle_setup-files/2_Registry_And_Verification/, double-click verify_prerequisites.bat

You should see a series of checks with [OK] messages:

[OK] Python found: Python 3.x.x
[OK] Conda found: conda 24.x.x
[OK] CUDA 12.8 found
[OK] Visual Studio Build Tools found
[OK] Git found: git version 2.x.x
[OK] Long paths enabled

If ANY check shows [FAIL]: Review that installation step and fix it before proceeding
Run verify_prerequisites.bat again until all show [OK]

⛔ STOP & CHECK: Do NOT proceed to Phase 2 until ALL checks pass!

PHASE 2: Automated ComfyUI + Hunyuan3D Installation

Pre-Installation Setup

Bundle Folder Structure:

bundle_setup-files/
├── START_HERE.txt
├── 1_Installers/
│   ├── Miniconda3-latest-Windows-x86_64.exe
│   ├── cuda_12.8.0_windows_10.exe
│   ├── vs_BuildTools.exe
│   └── Git-2.xx.x-64-bit.exe
├── 2_Registry_And_Verification/
│   ├── enable_long_paths.reg
│   └── verify_prerequisites.bat
├── 3_Automated_Install/
│   ├── install_comfyui_hunyuan3d.bat
│   ├── install_comfyui_hunyuan3d.py
│   ├── requirements_fixed.txt
│   └── ComfyUI-Hunyuan3D-2_1.zip ← YOU COPY HERE
└── 4_Testing_And_Cleanup/
    ├── test_hunyuan3d.bat
    └── cleanup_installation.bat

Prepare the Hunyuan3D files:
- You should have received ComfyUI-Hunyuan3D-2_1.zip separately
- Step 1: Copy ComfyUI-Hunyuan3D-2_1.zip to bundle_setup-files/3_Automated_Install/
- Step 2: Right-click the zip file → Extract All → Extract to 3_Automated_Install\ folder (extract in-place)
- Step 3: Delete the ComfyUI-Hunyuan3D-2_1.zip file after extraction
- RESULT: You should see a ComfyUI-Hunyuan3D-2_1 folder (NOT a .zip) in 3_Automated_Install/

Running the Automated Installer

Start the installer:
- In bundle_setup-files/3_Automated_Install/, double-click install_comfyui_hunyuan3d.bat
- A black console window will open - DO NOT CLOSE IT!
- Script will check if Python is available
- If check passes, installation begins automatically
What the script does (fully automated):
- Creates conda environment "comfyui_py311" with Python 3.11
- Installs PyTorch 2.9.0 with CUDA 12.8 support
- Clones ComfyUI from GitHub
- Installs 50+ Python packages (AI, 3D, image processing)
- Extracts and configures Hunyuan3D nodes
- Compiles custom GPU acceleration code (custom_rasterizer, mesh_inpaint_processor)
- Verifies all components are working
- Creates desktop shortcut: "ComfyUI Hunyuan3D"
During installation, you will see:
- [STEP 1/13] through [STEP 13/13] progress indicators
- Package installation progress bars
- Compilation output (lots of technical text - this is normal)
- [OK] or [SUCCESS] messages for each completed step
- TOTAL TIME: 30-45 minutes (depending on internet speed)

Installation complete when you see:

========================================
INSTALLATION COMPLETE!
========================================

Desktop shortcut created: ComfyUI Hunyuan3D

To start ComfyUI:
1. Double-click desktop shortcut, OR
2. Run: start_comfyui.bat

First run will download AI models (~13GB) - please be patient.

Screenshot: Console showing "INSTALLATION COMPLETE!" message with all steps marked [OK]

All 13 steps should show [OK] or [SUCCESS] - this confirms successful installation

First Launch

Start ComfyUI:
- Double-click the "ComfyUI Hunyuan3D" shortcut on your desktop
- A black console window will open (don't close this!)
First-time model download (IMPORTANT):
- On first launch, ComfyUI will download AI models (~13GB)
- You'll see: "Downloading hunyuan3d-dit-v2-1..." and "Downloading hunyuan3d-paintpbr-v2-1..."
- This takes 15-30 minutes depending on internet speed
- DO NOT CLOSE the console window during download

ComfyUI is ready when you see:

To see the GUI go to: http://127.0.0.1:8188

Open the interface:
- Open your web browser (Chrome, Edge, Firefox)
- Go to: http://127.0.0.1:8188
- You should see the ComfyUI interface

Verify Hunyuan3D nodes are loaded:

In the console window, scroll up and look for:

Loading custom nodes:
  [OK] ComfyUI-Hunyuan3D-2_1 loaded
  Nodes: AvaHy_21_MeshGenerator, AvaHy_21_VAEDecode, ...

Screenshot: ComfyUI web interface at http://127.0.0.1:8188

The node-based workflow interface - this is what success looks like!

Screenshot: Console window showing "[OK] ComfyUI-Hunyuan3D-2_1 loaded" message

Scroll up in the console to find this confirmation that nodes loaded correctly

Using ComfyUI with Hunyuan3D

Daily Usage

Every time you want to use ComfyUI:

Double-click "ComfyUI Hunyuan3D" desktop shortcut
Wait for console to show: "To see the GUI go to: http://127.0.0.1:8188"
Open browser to: http://127.0.0.1:8188

To close ComfyUI:

Close the browser tab
In the console window, press Ctrl + C
Close the console window

Loading a Workflow

Sample workflows are in: C:\AI\ComfyUI_Hunyuan3D\ComfyUI\custom_nodes\ComfyUI-Hunyuan3D-2_1\workflows\
In ComfyUI web interface:
- Click "Load" button
- Navigate to workflows folder
- Select a .json workflow file
- Click "Open"

Generating 3D Models

Load a workflow (see above)
Upload an image (drag & drop into "Load Image" node)
Click "Queue Prompt" button
Processing time: 4-7 minutes per model (RTX 4090)
Output files saved to: C:\AI\ComfyUI_Hunyuan3D\ComfyUI\output\

Troubleshooting

Installation Issues

Problem: `conda: command not found`

Solution:

Restart Command Prompt, or restart computer
Verify Miniconda is in PATH: where conda

Problem: `nvcc: command not found`

Solution:

CUDA not installed correctly
Verify: dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin\nvcc.exe"
If missing, reinstall CUDA 12.8

Problem: Compilation errors mentioning "vcvarsall.bat not found"

Solution:

Visual Studio Build Tools not installed correctly
Verify: dir "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat"
If missing, reinstall Build Tools with all 8 individual components

Problem: Python package installation fails with "No space left on device"

Solution:

Free up disk space (need 100GB total free space)
Clear temp files: cleanmgr in Start menu

Problem: Git clone fails with "filename too long"

Solution:

Long paths not enabled
Run: git config --global core.longpaths true
Enable in Windows registry (see Step 5 in Phase 1)

Runtime Issues

Problem: Console shows errors on startup

Solution:

Check: ComfyUI-Hunyuan3D-2_1 nodes loaded correctly
Look for: [OK] ComfyUI-Hunyuan3D-2_1 loaded in console
If missing, re-run installer: python install_comfyui_hunyuan3d.py --reinstall-nodes

Problem: "CUDA out of memory" error

Solution:

Your GPU has insufficient VRAM
Try: Close other GPU-intensive applications
Minimum required: 12GB VRAM

Problem: Models not downloading

Solution:

Check: Internet connection and firewall settings
Models download to: C:\Users\[YourName]\.cache\hy3dgen\tencent\Hunyuan3D-2.1\
Can manually download and place in this folder

Problem: Slow performance (>15 minutes per model)

Solution:

Check: CUDA is being used (not CPU)
In console, look for: "CUDA available: True"
If False, reinstall CUDA Toolkit 12.8

File Locations Reference

Component	Location
Installation Root	`C:\AI\ComfyUI_Hunyuan3D\`
ComfyUI	`C:\AI\ComfyUI_Hunyuan3D\ComfyUI\`
Hunyuan3D Nodes	`C:\AI\ComfyUI_Hunyuan3D\ComfyUI\custom_nodes\ComfyUI-Hunyuan3D-2_1\`
Workflows	`C:\AI\ComfyUI_Hunyuan3D\ComfyUI\custom_nodes\ComfyUI-Hunyuan3D-2_1\workflows\`
Output Files	`C:\AI\ComfyUI_Hunyuan3D\ComfyUI\output\`
AI Models Cache	`C:\Users\[YourName]\.cache\hy3dgen\tencent\Hunyuan3D-2.1\`
Conda Environment	`C:\Users\[YourName]\.conda\envs\comfyui_py311\`
Startup Script	`C:\AI\ComfyUI_Hunyuan3D\start_comfyui.bat`
Desktop Shortcut	`C:\Users\[YourName]\Desktop\ComfyUI Hunyuan3D.lnk`

Support & Documentation

Log Files

If something goes wrong, these files contain detailed information:

Installation log: C:\AI\ComfyUI_Hunyuan3D\installation_log.txt
ComfyUI console: (visible in the black console window)

For Technical Support

Provide these details:

Screenshot of error message
Contents of installation_log.txt

Output of these commands:

conda --version
nvcc --version
python --version

Appendix: What Gets Installed

Software Components

Miniconda: Python environment manager
Python 3.11: Programming language (isolated in conda environment)
CUDA Toolkit 12.8: NVIDIA GPU computing platform
Visual Studio Build Tools 2022: C++ compiler
Git: Version control system
ComfyUI: Node-based AI workflow interface
PyTorch 2.9.0: Deep learning framework
50+ Python packages: AI, 3D processing, image processing libraries

Disk Space Usage

Miniconda: ~500MB
CUDA Toolkit: ~3GB
VS Build Tools: ~5GB
Git: ~250MB
ComfyUI + packages: ~8GB
AI models: ~13GB
TOTAL: ~30GB

Network Usage (Downloads)

Software installers: ~8GB
Python packages: ~3GB
AI models (first run): ~13GB
TOTAL: ~24GB

Executive Installation Guide

What This Software Does

Business Value

System Requirements

Hardware:

Software Prerequisites (to be installed):

Installation Overview

PHASE 1: Foundation Software (Manual Installation) ~1 hour

PHASE 2: ComfyUI + Hunyuan3D (Automated Script) ~30-45 min

PHASE 1: Foundation Software Installation

Step 1: Install Miniconda (Python Environment Manager)

Installation:

CRITICAL VERIFICATION:

Also verify conda:

Step 2: Install CUDA Toolkit 12.8 (NVIDIA GPU Computing)

Installation:

Step 3: Install Visual Studio 2022 Build Tools (C++ Compiler)

Installation:

CRITICAL STEP 1 - Select Workload:

CRITICAL STEP 2 - Select Individual Components:

Verify installation:

Step 4: Install Git for Windows (Version Control)

Installation:

Configure Git for long paths (CRITICAL for ComfyUI):

Step 5: Enable Long Paths in Windows (CRITICAL)

Steps:

PHASE 1 COMPLETE - VERIFICATION

PHASE 2: Automated ComfyUI + Hunyuan3D Installation

Pre-Installation Setup

Running the Automated Installer

Installation complete when you see:

First Launch

Using ComfyUI with Hunyuan3D

Daily Usage

Loading a Workflow

Generating 3D Models

Troubleshooting

Installation Issues

Problem: conda: command not found

Problem: nvcc: command not found

Problem: Compilation errors mentioning "vcvarsall.bat not found"

Problem: Python package installation fails with "No space left on device"

Problem: Git clone fails with "filename too long"

Runtime Issues

Problem: Console shows errors on startup

Problem: "CUDA out of memory" error

Problem: Models not downloading

Problem: Slow performance (>15 minutes per model)

File Locations Reference

Support & Documentation

Log Files

For Technical Support

Appendix: What Gets Installed

Software Components

Disk Space Usage

Network Usage (Downloads)

Problem: `conda: command not found`

Problem: `nvcc: command not found`