How to Install and Run Locally Hunyuan3D-2 – Best Image/Text to 3D Objects (CAD) AI Model on Linux Ubuntu

In this tutorial, we explain how to install and run locally Hunyuan3D-2 on Linux Ubuntu. Hunyuan3D is arguably one of the best AI models for text-to-3D model and image-to-3D model generation. The YouTube tutorial is given below.

Installation Procedure

First of all, our computer specs are

• NVIDIA 3090 GPU
• 64 GB RAM
• Intel i9 processor

We are using Linux Ubuntu 24.04, Python 3.12, GCC compiler 3.13, and NVIDIA CUDA Compiler 12.6. Note that currently, PyTorch is not working on Python 3.13.

First of all, you need to install the NVIDIA CUDA Toolkit on your system. To do that, follow the tutorial given below.

Then, open a terminal and make sure that NVIDIA CUDA compilers are installed by typing

nvcc --version

If they are installed you should obtain a response and CUDA version. Next, make sure that you have Python installed on your system. To do that, in the terminal type

python3 --version

In our case, the Python version 3.12.

Next, you need to install git:

sudo apt install git-all

Then, you need to clone the remote repository. To do that, type

cd ~

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

cd Hunyuan3D-2

Then, you need to create a Python virtual environment and activate it.

sudo apt install python3.12-venv
python3 -m venv env1
source env1/bin/activate

Next, you need to install the necessary libraries. First, you need the Huggingface hub library for downloading the remote repositories:

pip install huggingface_hub

Then, you need to install PyTorch. For that purpose, go to the official PyTorch website

https://pytorch.org/get-started/locally

and use the selection table to generate the pip installation command. In our case, the installation command is

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

Next, you need to run the installation commands

pip install -r requirements.txt
# for texture
cd hy3dgen/texgen/custom_rasterizer
python3 setup.py install
cd ../../..
cd hy3dgen/texgen/differentiable_renderer
python3 setup.py install

Finally, create the model folder

mkdir models

The next step is to download models. To do that, create a Python file called download.py:

from huggingface_hub import snapshot_download

snapshot_download(repo_id="tencent/Hunyuan3D-2",
                  local_dir="/home/ahaber/Hunyuan3D-2/models")

Adjust the paths in this file such that they match the patch on your system (see the YouTube video tutorial). Next, you need to have test images. They are given below and you can download them. Save them as test1.png, test2.png, test3.png, and test4.png in the workspace folder.

Here is the code for testing the model:

# Open Source Model Licensed under the Apache License Version 2.0
# and Other Licenses of the Third-Party Components therein:
# The below Model in this distribution may have been modified by THL A29 Limited
# ("Tencent Modifications"). All Tencent Modifications are Copyright (C) 2024 THL A29 Limited.

# Copyright (C) 2024 THL A29 Limited, a Tencent company.  All rights reserved.
# The below software and/or models in this distribution may have been
# modified by THL A29 Limited ("Tencent Modifications").
# All Tencent Modifications are Copyright (C) THL A29 Limited.

# Hunyuan 3D is licensed under the TENCENT HUNYUAN NON-COMMERCIAL LICENSE AGREEMENT
# except for the third-party components listed below.
# Hunyuan 3D does not impose any additional limitations beyond what is outlined
# in the repsective licenses of these third-party components.
# Users must comply with all terms and conditions of original licenses of these third-party
# components and must ensure that the usage of the third party components adheres to
# all relevant laws and regulations.

# For avoidance of doubts, Hunyuan 3D means the large language models and
# their software and algorithms, including trained model weights, parameters (including
# optimizer states), machine-learning model code, inference-enabling code, training-enabling code,
# fine-tuning enabling code and other elements of the foregoing made publicly available
# by Tencent in accordance with TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT.

import torch
from PIL import Image

from hy3dgen.rembg import BackgroundRemover
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline, FaceReducer, FloaterRemover, DegenerateFaceRemover
from hy3dgen.text2image import HunyuanDiTPipeline

image_name='test4.png'
fileName='mesh4.glb'

def image_to_3d(image_path=image_name):
    rembg = BackgroundRemover()
    model_path = '/home/ahaber/Hunyuan3D-2/models'

    image = Image.open(image_path)

    if image.mode == 'RGB':
        image = rembg(image)

    pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(model_path)

    mesh = pipeline(image=image, num_inference_steps=30, mc_algo='mc',
                    generator=torch.manual_seed(2025))[0]
    mesh = FloaterRemover()(mesh)
    mesh = DegenerateFaceRemover()(mesh)
    mesh = FaceReducer()(mesh)
    mesh.export('mesh.glb')

    try:
        from hy3dgen.texgen import Hunyuan3DPaintPipeline
        pipeline = Hunyuan3DPaintPipeline.from_pretrained(model_path)
        mesh = pipeline(mesh, image=image)
        mesh.export('texture.glb')
    except Exception as e:
        print(e)
        print('Please try to install requirements by following README.md')


def text_to_3d(prompt='a car'):
    rembg = BackgroundRemover()
    t2i = HunyuanDiTPipeline('Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled')
    model_path = '/home/ahaber/Hunyuan3D-2/models'
    i23d = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(model_path)

    image = t2i(prompt)
    image = rembg(image)
    mesh = i23d(image, num_inference_steps=30, mc_algo='mc')[0]
    mesh = FloaterRemover()(mesh)
    mesh = DegenerateFaceRemover()(mesh)
    mesh = FaceReducer()(mesh)
    mesh.export('t2i_demo.glb')


def image_to_3d_fast(image_path=image_name):
    rembg = BackgroundRemover()
    model_path = '/home/ahaber/Hunyuan3D-2/models'

    image = Image.open(image_path)

    if image.mode == 'RGB':
        image = rembg(image)

    pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
        model_path,
        subfolder='hunyuan3d-dit-v2-0-fast',
        variant='fp16'
    )

    mesh = pipeline(image=image, num_inference_steps=30, mc_algo='mc',
                    generator=torch.manual_seed(2025))[0]
    mesh = FloaterRemover()(mesh)
    mesh = DegenerateFaceRemover()(mesh)
    mesh = FaceReducer()(mesh)
    mesh.export(fileName)


if __name__ == '__main__':
    image_to_3d_fast()
    # image_to_3d()
    # text_to_3d()

Adjust the model path and image name in this code and run it (for more details see the YouTube video). This code will produce the file with an extension glb. This is a 3D model file and you can use Blender to open this file. For more details see the YouTube tutorial.