Skip to content
Get packs

Guide · Open source

How to use TRELLIS.2: install, run image-to-3D and export GLB

Updated · written with AI from the project's own documentation and checked against our catalogue data

TRELLIS.2 is Microsoft's open-source 4-billion-parameter model that turns a single image into a 3D object with textured mesh and PBR materials. This guide explains what you need before installing, how to set up the environment, how to run the minimal example and how to export a GLB file. It is written for readers comfortable with Python and a Linux terminal.

TRELLIS.2microsoft/TRELLIS.2 · ★ 12.6k · MIT

Quick start

  1. 1Check your hardware. Confirm you are on Linux with an NVIDIA GPU that has at least 24GB of memory, as the README requires.
  2. 2Clone the repository. Clone microsoft/TRELLIS.2 with --recursive so submodules are included, then cd into TRELLIS.2.
  3. 3Install dependencies. Run the setup.sh command with --new-env and the listed flags, after setting CUDA_HOME if you have multiple CUDA versions.
  4. 4Activate the environment. Activate the trellis2 conda environment created by the setup script before running any Python code.
  5. 5Run example.py. Run the minimal example to load TRELLIS.2-4B, generate a mesh from T.png and save sample.mp4 and sample.glb.
  6. 6Add transparency if needed. Import the GLB into your 3D software and connect the texture alpha channel to opacity manually, since it is off by default.

What TRELLIS.2 does and what you need first

TRELLIS.2 is a large 3D generative model designed for image-to-3D generation. It outputs textured meshes with Base Color, Roughness, Metallic and Opacity attributes, and the project's example exports them as GLB files. The code is MIT licensed and the pretrained weights are published on Hugging Face as TRELLIS.2-4B.

  • System: Linux. The README says the code is currently tested only on Linux.
  • Hardware: an NVIDIA GPU with at least 24GB of memory. The README says this is necessary and reports verification on A100 and H100 GPUs.
  • Software: CUDA Toolkit (12.4 recommended), Conda (recommended for managing dependencies), and Python 3.8 or higher.

Clone the repository and install dependencies

Clone the repository with its submodules, then enter the project folder. The setup script creates a conda environment named trellis2 by default when you use --new-env.

Read the notes in the README before running the setup command. If you have several CUDA Toolkit versions, set CUDA_HOME to the one you want. GPUs without flash-attn support, such as the NVIDIA V100, need xformers installed manually and the ATTN_BACKEND environment variable set to xformers.

  • If a step fails, the README suggests installing the dependencies one at a time, using one flag per run.
  • Run . ./setup.sh --help to see all options.
git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive cd TRELLIS.2 . ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm

Run the minimal image-to-3D example

The repository includes example.py. It loads the TRELLIS.2-4B pipeline, runs it on an image from assets/example_image, renders a video and exports a GLB. The README notes that the pipeline needs to be moved to the GPU with pipeline.cuda().

Running the script creates two files: sample.mp4, a video of the asset with PBR materials under environmental lighting, and sample.glb, the PBR-ready 3D asset.

  • Input image used in the example: assets/example_image/T.png
  • Environment map used for rendering: assets/hdri/forest.exr
  • Export settings in the example include texture_size 4096 and decimation_target 1000000.
from trellis2.pipelines import Trellis2ImageTo3DPipeline pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B") pipeline.cuda() image = Image.open("assets/example_image/T.png") mesh = pipeline.run(image)[0]

Understand transparency in the exported GLB

The README says the GLB is exported in OPAQUE mode by default. The alpha channel is kept in the texture map but is not active. To use transparency, you must import the asset into your 3D software and connect the texture's alpha channel to the material's opacity or alpha input yourself.

Try the web demo or texture an existing shape

The repository provides app.py for a simple image-to-3D web demo. Run it, then open the address shown in the terminal. For generating PBR textures on a 3D shape you already have, the README points to example_texturing.py and app_texturing.py.

  • Image-to-3D web demo: app.py
  • PBR texture generation example: example_texturing.py
  • PBR texture web demo: app_texturing.py
python app.py

What people use it for

  • Generating a quick textured 3D base model from a reference image for a designer or artist to refine.
  • Experimenting with image-to-3D generation as a researcher or developer.
  • Producing a GLB with PBR materials for import into a 3D software package.
  • Studying the O-Voxel representation and the model's structured latents as described in the paper.

Frequently asked questions

Is TRELLIS.2 free to use?

TRELLIS.2 is released under the MIT license, and its pretrained weights are published on Hugging Face. The source does not list any pricing, so you should check the license file and model card for the terms that apply to your use.

What GPU do I need for TRELLIS.2?

The README says an NVIDIA GPU with at least 24GB of memory is necessary. The code has been verified on NVIDIA A100 and H100 GPUs.

Does TRELLIS.2 work on Windows or macOS?

The README says the code is currently tested only on Linux. The source does not claim support for Windows or macOS.

How do I install TRELLIS.2?

Clone the GitHub repository with --recursive, enter the folder and run the setup.sh script with --new-env and the flags for the components you need. The setup requires conda, the CUDA Toolkit (12.4 recommended) and Python 3.8 or higher.

Why is my GLB texture not transparent?

The GLB is exported in OPAQUE mode by default. The alpha channel is stored in the texture but must be connected to the material's opacity input manually in your 3D software.

What are alternatives to TRELLIS.2?

The project lists TRELLIS, Hunyuan3D, TripoSR and Stable Fast 3D as comparable projects. Those are worth trying if you lack a 24GB NVIDIA GPU or want a simpler setup, though this guide does not benchmark them against TRELLIS.2.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

TRELLIS.2 suits researchers and developers with a Linux machine, an NVIDIA GPU with at least 24GB of memory, and comfort with Python and CUDA setup. If you need a point-and-click tool, a Windows or macOS setup, or a card with less memory, pick one of the comparable projects such as TripoSR or Stable Fast 3D.

Install options & downloads