How to Install and Run Hunyuan3D-2 on macOS: A Step-by-Step Guide

Introduction

Setting up Hunyuan3D-2 locally on a Mac involves several steps, including installing necessary software, configuring the environment, and running the model. Hunyuan3D-2, developed by Tencent, is a powerful AI model that converts 2D images into 3D objects, making it a valuable tool for artists, designers, and developers. This guide provides a comprehensive walkthrough of the installation process, ensuring a smooth setup on macOS.

Prerequisites

Before proceeding with the installation, ensure that your system meets the following requirements:

Operating System: macOS (preferably the latest version).
Python: Version 3.8 or higher.
Homebrew: A package manager for macOS.
Git: For cloning repositories.
CUDA: If using an NVIDIA GPU (optional for CPU usage).
PyTorch: Required deep-learning framework.

Method 1: The "One-Click" Solution (Pinokio)

Best for: Users who want it to "just work" without touching the terminal.

Pinokio is an AI browser that scripts the entire installation process (environment, dependencies, model downloading) for you. This is currently the most reliable way to run Hunyuan3D-2 on Mac without dependency hell.

Download Pinokio: Go to pinokio.computer and install the application for macOS (Apple Silicon).
Launch & Search: Open Pinokio and use the "Discover" tab to search for "Hunyuan3D-2".
Install: Click the card and select Download. Pinokio will automatically:
- Install Python, PyTorch, and necessary libraries.
- Clone the repository.
- Download the heavy model weights (approx. 50GB+).
Run: Once finished, click Start. It will launch the Gradio web interface (usually http://127.0.0.1:7860) in your browser.

Note: If the "Texture" step fails or hangs, it is likely due to the missing CUDA rasterizer. You may be limited to generating the untextured 3D mesh (shape) only.

Method 2: The "Professional" Solution (ComfyUI)

Best for: Users who want more control, better performance, and a node-based workflow.

The community-built wrapper for ComfyUI often handles Mac compatibility better than the official repo.

Install ComfyUI:
- Clone the repo: git clone https://github.com/comfyanonymous/ComfyUI
- Install dependencies: pip install -r requirements.txt
Install ComfyUI Manager:
- cd ComfyUI/custom_nodes
- git clone https://github.com/ltdrdata/ComfyUI-Manager.git
Install Hunyuan Wrapper:
- Run ComfyUI (python main.py).
- Open the Manager menu inside the UI.
- Search for and install "ComfyUI-Hunyuan3DWrapper" (by Kijai).
- Restart ComfyUI.
Download Models:
- The wrapper should attempt to download models automatically to ComfyUI/models/hunyuan3d.
- If not, manually download hunyuan3d-dit-v2-0 and hunyuan3d-paint-v2-0 from Hugging Face.
Load Workflow:
- Drag the example workflow JSON (found in the wrapper's GitHub examples) into your ComfyUI window.
- This method is superior because if the "Texture" node fails, you can simply bypass it and still get your high-quality 3D mesh.

Method 3: The Native Developer Method (Terminal)

Best for: Developers who want to debug code or contribute.

Warning: The texture module (custom_rasterizer) often fails to compile on macOS because it contains raw CUDA code. You may need to edit files to skip it.

Step 1: Install System Dependencies
Open Terminal and run:

bash# Install Homebrew if you haven't /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install Python 3.10 or 3.11 (3.12 can be buggy with some AI tools) brew install python@3.10 git cmake protobuf wget

Step 2: Clone and Setup Environment

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

# Create a virtual environment to keep your Mac clean
python3.10 -m venv venv
source venv/bin/activate

# Install dependencies # NOTE: We skip specific versions if they conflict with Mac
pip install --upgrade pip
pip install -r requirements.txt
pip install "torch>=2.2.0" torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

Step 3: Attempt to Build Rasterizers (The Tricky Part)
The official guide asks you to run these commands. Try them, but if they fail, proceed to Step 4 anyway.

bash# Attempt to install custom rasterizer cd hy3dgen/texgen/custom_rasterizer
python setup.py install # Attempt to install differentiable renderer cd ../differentiable_renderer
python setup.py install # Return to root cd ../../..

If these fail with "nvcc not found" or "CUDA error", you will not be able to generate textures locally using the official pipeline.

Step 4: Run the Application
Use the following flags to optimize for Apple Silicon:

bashpython gradio_app.py --low_vram_mode --use_lite

--low_vram_mode: Essential for Macs with <64GB RAM.
--use_lite (if available): Loads smaller model variants.

Summary of Limitations on macOS

Shape Generation: Works well. You will get high-quality meshes (.obj / .glb).
Texture Generation: Likely to fail or be extremely slow because nvdiffrast (the texturing engine) heavily relies on NVIDIA architecture.
Speed: Expect generation times of 2-5 minutes per object on an M1/M2/M3 Max, compared to seconds on an RTX 4090.

OR

Installing Homebrew

Homebrew simplifies software installation on macOS. To install Homebrew, open the terminal and execute:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Installing Python

Python can be installed using Homebrew:

brew install python

Verify the installation:

python3 --version

Installing Git

If Git is not installed, install it via Homebrew:

brew install git

Installing PyTorch

Visit the official PyTorch website for macOS installation instructions. You can also install it using:

pip3 install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cpu

For GPU support, ensure appropriate NVIDIA drivers are installed.

Cloning Hunyuan3D-2 Repository

Clone the Hunyuan3D-2 repository from GitHub:

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

Navigate to the cloned directory:

cd Hunyuan3D-2

Setting Up the Environment

Installing Required Packages

Install all dependencies listed in requirements.txt:

pip3 install -r requirements.txt

Setting Up Texture Generation

Navigate to the texture generation directory:

cd hy3dgen/texgen/custom_rasterizer

Run the setup script:

python3 setup.py install

Running Hunyuan3D-2

Return to the main project directory:

cd ../../..

Start the application:

python3 app.py

The first run may take some time as required models are downloaded.

Using Hunyuan3D-2

Once running, Hunyuan3D-2 provides a Gradio web interface at:

http://localhost:7860

Uploading Images

Click the upload button.
Select a 2D image from your computer.
Adjust any settings if available.
Click Generate to create a 3D model.

Downloading Generated Models

After processing, download or preview your generated 3D model directly from the interface.

Troubleshooting Common Issues

Python Version Issues

Ensure Python 3.8 or higher is installed:

python3 --version

Upgrade if necessary.

Dependency Errors

If you encounter missing package errors, reinstall dependencies:

pip3 install -r requirements.txt --upgrade

Model Download Failures

If model downloads fail, check your internet connection and rerun:

python3 app.py

Conclusion

By following this guide, you can set up Hunyuan3D-2 on macOS and leverage its AI capabilities to convert 2D images into 3D models. This tool offers immense potential for applications in gaming, design, and virtual reality. Further integrations with Blender or Unity can expand its functionality for more advanced projects.