How to Install TRELLIS.2 Locally: Verified Linux Setup Guide

Microsoft's current TRELLIS.2 repository documents one supported local setup: Linux, an NVIDIA GPU with at least 24 GB of memory, CUDA tooling, Conda, and Python 3.8 or newer. The project says it has been verified on NVIDIA A100 and H100 GPUs. It does not currently document native Windows or macOS support.

This guide follows the upstream repository instead of mixing instructions from the older microsoft/TRELLIS project.

Official prerequisites

Read the official TRELLIS.2 README before installing. Requirements can change as the repository evolves.

1. Clone the correct repository

TRELLIS.2 is a separate codebase from the original TRELLIS project. Clone it recursively so its submodules are present:

git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive
cd TRELLIS.2

If you cloned without --recursive, initialize the missing submodules before continuing:

git submodule update --init --recursive

2. Confirm the CUDA toolchain

Check that the NVIDIA driver can see your GPU:

nvidia-smi

If more than one CUDA Toolkit is installed, point CUDA_HOME to the version you intend to compile against. The upstream example uses CUDA 12.4:

export CUDA_HOME=/usr/local/cuda-12.4

The driver, CUDA Toolkit, PyTorch build, and compiled extensions must agree. Do not copy an arbitrary PyTorch command from an older TRELLIS guide.

3. Run the upstream setup script

The official full setup command creates a trellis2 Conda environment and installs the main dependencies:

. ./setup.sh \
  --new-env \
  --basic \
  --flash-attn \
  --nvdiffrast \
  --nvdiffrec \
  --cumesh \
  --o-voxel \
  --flexgemm

The script defaults to Python 3.10, PyTorch 2.6.0, and CUDA 12.4 when --new-env is used. Run . ./setup.sh --help to see individual flags.

For a GPU that does not support FlashAttention, the upstream README recommends installing xformers and setting:

export ATTN_BACKEND=xformers

4. Verify the environment

Activate the environment if it is not already active:

conda activate trellis2

Then verify the core imports before downloading or running a full generation:

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
python -c "import o_voxel; print('o-voxel ready')"

If either command fails, fix the environment before moving on. A generation error is harder to diagnose when the basic CUDA or extension import is already broken.

5. Run the official example or web demo

The repository includes an image-to-3D example and a Gradio app:

python example.py

or:

python app.py

The example loads microsoft/TRELLIS.2-4B, generates a mesh, and demonstrates GLB export. See the official usage section for the current code.

No local GPU?

The web generator on trellis2.com runs remotely, so it does not require a local NVIDIA GPU or CUDA installation:

Open the TRELLIS 2 premium generator

This is a deployment choice made by trellis2.com, not a change to the upstream project's local hardware requirements.

Licensing

The TRELLIS.2 model and code are released under the MIT License. Some dependencies have their own licenses, so review the upstream license section before redistributing a bundled environment.

Related guides

• Verified TRELLIS.2 system requirements
• TRELLIS.2 troubleshooting checklist
• Export a generated GLB to Blender and game engines