A043-studios-ComfyUI_HunyuanWorldnode/INSTALL_GUIDE.md

📦 Complete Installation Guide for ComfyUI-HunyuanWorld

This guide provides step-by-step instructions for installing ComfyUI-HunyuanWorld from GitHub.

🎯 Quick Start (TL;DR)

cd ComfyUI/custom_nodes
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode
python install.py
# Restart ComfyUI

📋 Prerequisites

System Requirements

• OS: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+)
• Python: 3.8 or higher
• GPU: NVIDIA GPU with 4GB+ VRAM (recommended)
• RAM: 8GB+ system RAM
• Storage: 10GB+ free space (for models)

Software Requirements

• ComfyUI installed and working
• Git (for cloning the repository)
• Python package manager (pip)

🚀 Installation Methods

Method 1: ComfyUI Manager (Easiest)

1. Install ComfyUI Manager (if not already installed):

   cd ComfyUI/custom_nodes
   git clone https://github.com/ltdrdata/ComfyUI-Manager.git
   

2. Restart ComfyUI and you'll see the Manager button

3. Search and Install:

   • Click the Manager button
   • Search for "HunyuanWorld"
   • Click "Install"
   • Restart ComfyUI

Method 2: Git Clone (Recommended)

1. Navigate to ComfyUI custom_nodes directory:

   cd ComfyUI/custom_nodes
   

2. Clone the repository:

   git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
   

3. Navigate to the cloned directory:

   cd ComfyUI_HunyuanWorldnode
   

4. Run the installation script:

   python install.py
   

   Or install manually:

   pip install -r requirements.txt
   

5. Restart ComfyUI

Method 3: Download ZIP

1. Download the latest release:

   • Go to Releases
   • Download the latest ZIP file

2. Extract to ComfyUI:

   • Extract to ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode

3. Install dependencies:

   cd ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode
   python install.py
   

4. Restart ComfyUI

🔧 Advanced Installation

Virtual Environment (Recommended for Development)

# Create virtual environment
python -m venv hunyuanworld_env

# Activate virtual environment
# On Windows:
hunyuanworld_env\Scripts\activate
# On macOS/Linux:
source hunyuanworld_env/bin/activate

# Install ComfyUI-HunyuanWorld
cd ComfyUI/custom_nodes
git clone https://github.com/yourusername/ComfyUI-HunyuanWorld.git
cd ComfyUI-HunyuanWorld
pip install -r requirements.txt

Docker Installation (Coming Soon)

# Pull the image
docker pull yourusername/comfyui-hunyuanworld:latest

# Run with GPU support
docker run --gpus all -p 8188:8188 yourusername/comfyui-hunyuanworld:latest

Development Installation

# Clone with development dependencies
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode

# Install in development mode
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

🧪 Verification

Test Installation

1. Check if nodes are available:

   • Start ComfyUI
   • Right-click in the workflow area
   • Look for "HunyuanWorld" in the node menu

2. Run the test script:

   cd ComfyUI/custom_nodes/ComfyUI-HunyuanWorld
   python examples/simple_workflow.py
   

3. Check dependencies:

   python -c "import __init__; print('✅ Import successful')"
   

Expected Output

You should see nodes like:

• 🌍 HunyuanWorld: Model Loader (Real)
• 🌍 HunyuanWorld: Image to 3D (Real)
• 🌍 HunyuanWorld: Simple Image to 3D
• 🌍 HunyuanWorld: Hybrid Generator

🔍 Troubleshooting

Common Issues

"Module not found" errors

# Ensure you're in the right directory
cd ComfyUI/custom_nodes/ComfyUI-HunyuanWorld

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

"CUDA out of memory"

# Use low VRAM settings
# In the node settings:
# - Set low_vram_mode=True
# - Use precision="fp16"
# - Use model="tencent/Hunyuan3D-2mini"

"Hunyuan3D libraries not available"

# Install Hunyuan3D from source
git clone https://github.com/tencent/hunyuan3d-2.git
cd hunyuan3d-2
pip install -e .

Nodes not appearing in ComfyUI

1. Check ComfyUI console for error messages
2. Ensure ComfyUI was restarted after installation
3. Verify the installation directory is correct
4. Check file permissions

Getting Help

1. Check the logs: Look at ComfyUI console output for error messages
2. Search issues: Check GitHub Issues
3. Create an issue: Use the bug report template
4. Community support: Ask in ComfyUI Discord/Reddit

🔄 Updating

Update from Git

cd ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode
git pull origin main
pip install -r requirements.txt --upgrade

Update via ComfyUI Manager

1. Open ComfyUI Manager
2. Go to "Update" tab
3. Find ComfyUI-HunyuanWorld
4. Click "Update"

🗑️ Uninstallation

# Remove the directory
rm -rf ComfyUI/custom_nodes/ComfyUI-HunyuanWorld

# Or on Windows
rmdir /s ComfyUI\custom_nodes\ComfyUI-HunyuanWorld

📚 Next Steps

After successful installation:

1. Read the README: Check out usage examples and workflows
2. Try examples: Run the example workflows
3. Explore nodes: Experiment with different settings
4. Join community: Contribute to the project

🆘 Support

• 📖 Documentation: README.md
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues
• 🤝 Contributing: CONTRIBUTING.md

---

Happy 3D generating! 🌍✨