Setting Up Hunyuan3D-2 Locally on Ubuntu: A Step-by-Step Guide

Anas Mohammad -

Hunyuan3D-2 is an advanced open-source 3D modeling tool developed by Tencent, designed to generate high-resolution 3D assets from images and text. This guide provides a step-by-step approach to installing and configuring Hunyuan3D-2 on an Ubuntu machine.

System Requirements

Before installing Hunyuan3D-2, ensure your system meets the following requirements:

  • Operating System: Ubuntu 18.04 or later
  • Python: Version 3.9 or later
  • CUDA: Version 12.0 or later (for GPU acceleration)
  • PyTorch: Compatible with your CUDA version
  • Hardware:
    • A modern CPU (Intel i5/Ryzen 5 or better recommended)
    • At least 8 GB of RAM (16 GB+ recommended for larger models)
    • A compatible NVIDIA GPU (with CUDA support)

Installation Guide

Step 1: Install System Dependencies

Open a terminal and execute:

sudo apt update
sudo apt install git build-essential

Step 2: Install Python and Pip

If Python is not installed, install it using:

sudo apt install python3 python3-pip python3-venv

Step 3: Clone the Hunyuan3D-2 Repository

Download the Hunyuan3D-2 source code from GitHub:

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

Step 4: Set Up a Virtual Environment

Creating a virtual environment ensures package dependencies remain isolated:

python3 -m venv hunyuan3d-env
source hunyuan3d-env/bin/activate

Step 5: Install PyTorch

Install PyTorch based on your CUDA version. For CUDA 12.1, use:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

For other CUDA versions, check the official PyTorch installation guide.

Step 6: Install Required Packages

Install additional dependencies listed in requirements.txt:

pip install -r requirements.txt

Step 7: Download Pretrained Models

Hunyuan3D-2 requires pretrained models from Hugging Face. Install the Hugging Face CLI:

pip install huggingface_hub[cli]

Then download the models:

mkdir weights
huggingface-cli download tencent/Hunyuan3D-2 --local-dir ./weights

You may need to log in to Hugging Face to access the models.

Step 8: Install Performance-Optimizing Packages (Optional)

For better performance, install xformers and flash_attn:

pip install xformers --index-url https://download.pytorch.org/whl/cu121
pip install flash_attn --index-url https://download.pytorch.org/whl/cu121

Step 9: Verify Installation

Run Python and check if PyTorch is installed correctly:

python
>>> import torch
>>> print(torch.__version__)

If the version prints without errors, PyTorch is installed successfully.

Running Hunyuan3D-2

To start Hunyuan3D-2, navigate to the project directory and run:

cd path/to/Hunyuan3D-2/hy3dgen/
python app.py

This launches the application, allowing you to generate 3D models.

Using Hunyuan3D-2

Hunyuan3D-2 supports both image-to-3D and text-to-3D generation.

Generating 3D Models from Images

Use the following Python snippet to create a 3D model from an image:

from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
mesh = pipeline(image='path/to/your/image.png')

Generating 3D Models from Text

For text-to-3D model generation, use:

from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
mesh = pipeline(text='A detailed description of your desired object.')

Troubleshooting Common Issues

1. CUDA Errors

Ensure your NVIDIA drivers are up-to-date and match your CUDA version.

2. Package Version Conflicts

If dependency issues arise, specify exact package versions in requirements.txt.

3. Memory Errors

Try reducing input image sizes or increasing RAM if memory errors occur.

4. Model Download Failures

Ensure a stable internet connection and login to Hugging Face before downloading.

Conclusion

By following this guide, you can successfully install and run Hunyuan3D-2 on your Ubuntu machine. This tool provides powerful 3D generation capabilities from images and text prompts, making it an excellent choice for artists, developers, and researchers.

For further details, visit the Hunyuan3D-2 GitHub repository.

References:
[1] Digital Alps - Hunyuan3D-2 Overview
[2] Lizedin
[3] YouTube - Hunyuan3D-2 Demos
[4] YouTube - Hunyuan3D-2 Review
[5] Reddit - Stable Diffusion Discussion
[6] Hacker News - Hunyuan3D-2