trellis2.comtrellis2.com

How to Install Trellis 2: Complete Setup Guide (2025)

2025/03/20

You've seen the viral demos—upload a single image, get a fully editable 3D model in seconds. TRELLIS 2 is revolutionizing 3D content creation, but here's the reality: getting it running locally can be frustrating, especially if you're not comfortable with Python environments and GPU drivers.

Don't worry. In this guide, I'll walk you through the complete TRELLIS 2 installation process, from system requirements to troubleshooting common issues. Whether you're on Windows, Mac, or Linux, I've got you covered. Plus, I'll show you a no-code alternative that skips all the setup headaches.

Quick Start: What You Need to Know

TL;DR: TRELLIS 2 requires:

  • GPU: NVIDIA RTX 3060 or better (6GB+ VRAM recommended)
  • RAM: 16GB minimum, 32GB recommended
  • Storage: 50GB free space
  • OS: Windows 10/11, Ubuntu 20.04+, or macOS (with some limitations)
  • Python: 3.8-3.10 with CUDA support

If your hardware doesn't meet these requirements, don't panic—I'll show you alternatives later.

Method 1: Local Installation (For Technical Users)

Prerequisites Checklist

Before diving in, make sure you have:

  1. NVIDIA GPU with CUDA support (check with command: nvidia-smi)
  2. Python 3.8-3.10 installed
  3. Git installed
  4. Virtual environment tool (conda or venv)

Step 1: Clone the TRELLIS 2 Repository

Open your terminal or command prompt:

git clone https://github.com/Microsoft/TRELLIS.git
cd TRELLIS

Step 2: Create Virtual Environment

Using conda (recommended):

conda create -n trellis python=3.10
conda activate trellis

Using venv:

python -m venv trellis_env
source trellis_env/bin/activate  # On Windows: trellis_env\Scripts\activate

Step 3: Install Dependencies

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install -e .
pip install gradio

Note: The CUDA version (cu118) should match your NVIDIA driver.

Step 4: Download Model Weights

TRELLIS 2 uses pre-trained models that need to be downloaded:

python scripts/download_models.py

This will download about 15GB of model weights.

Step 5: Launch TRELLIS 2

For Gradio UI (recommended for beginners):

python app.py

This will launch a web interface at http://localhost:7860.

Method 2: Docker Installation (Cleaner Environment)

If you want to avoid dependency conflicts, Docker is your friend:

docker pull ghcr.io/microsoft/trellis:latest
docker run -p 7860:7860 ghcr.io/microsoft/trellis:latest

This automatically handles all dependencies and isolates TRELLIS 2 from your system.

Common Installation Issues and Fixes

Issue 1: CUDA Out of Memory

Symptom: Error: CUDA out of memory

Solution:

  1. Close other GPU-intensive applications
  2. Reduce batch size in config
  3. Use the 4B parameter model instead of 8B
  4. Add system swap space (32GB+)

Issue 2: PyTorch CUDA Mismatch

Symptom: Error: RuntimeError: CUDA version mismatch

Solution:

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

Issue 3: Missing Dependencies on Mac

Symptom: MPS (Metal Performance Shaders) not working

Solution:

pip install torch torchvision
export PYTORCH_ENABLE_MPS_FALLBACK=1

Warning: Mac performance is significantly slower than NVIDIA GPUs (5-10x). Expect 30-60 seconds per generation.

Issue 4: File Not Found During Model Download

Symptom: Error downloading model weights

Solution:

  1. Check your internet connection (model files are 15GB+)
  2. Use a VPN if you're in China
  3. Manually download from HuggingFace and place in cache folder

System Requirements by Use Case

Minimum (Playable)

  • GPU: GTX 1660 Ti (6GB VRAM)
  • RAM: 16GB
  • Result: 15-30 seconds per generation, occasional crashes
  • GPU: RTX 3060 Ti or 4060 Ti (8GB+ VRAM)
  • RAM: 32GB
  • Result: 5-10 seconds per generation, stable

Optimal (Production)

  • GPU: RTX 4090 or A6000 (24GB+ VRAM)
  • RAM: 64GB
  • Result: Less than 3 seconds per generation, batch processing

No-Code Alternative: Skip the Setup

If you're not technical or just want to test TRELLIS 2 quickly, there are web-based options:

  1. HuggingFace Spaces: Try TRELLIS 2 Online

    • Free tier available
    • No installation required
    • Queue times during peak hours

  2. Replicate: TRELLIS 2 API

    • Pay-per-use ($0.01-0.05 per generation)
    • RESTful API for integration
    • Faster than HuggingFace

  3. Commercial Tools: Alternative 3D Gen Tools

    • User-friendly interfaces
    • Additional features (texturing, rigging)
    • Higher cost but more polished

Trade-off: Web versions have queue times and usage limits. Local installation gives you unlimited generations and full control.

What's Next? Getting the Most Out of TRELLIS 2

Once you have TRELLIS 2 installed, here's how to level up:

Learn the Technical Side

Read: How TRELLIS 2 Works Under the Hood

Understanding O-Voxel and SLAT will help you troubleshoot issues and optimize your generations.

Compare with Alternatives

Read: TRELLIS 2 vs Meshy vs Tripo vs CSM

Know when to use TRELLIS 2 and when other tools might be better for your use case.

Optimize Your Workflow

  • Batch processing: Generate multiple models overnight
  • Custom fine-tuning: Train on your own dataset
  • Format export: Learn OBJ/GLB export for game engines

FAQ: TRELLIS 2 Installation

Can I run TRELLIS 2 on a Mac?

Yes, but with caveats. M1/M2 Macs use the MPS backend, which is 5-10x slower than NVIDIA GPUs. It works for testing but isn't ideal for production.

What if I don't have a GPU?

You have two options:

  1. Use the web version (HuggingFace/Replicate)
  2. Run on CPU (expect 2-5 minutes per generation—not recommended)

Is TRELLIS 2 free?

Yes, the open-source version is free for non-commercial use. Commercial licensing is available through Microsoft.

How much disk space do I need?

  • Base installation: about 5GB
  • Model weights: about 15GB
  • Working space: about 10GB
  • Total: 30-50GB recommended

Can I install multiple TRELLIS versions?

Yes, using separate virtual environments or Docker containers. This is useful for testing different model versions.

Why is my generation so slow?

Common causes:

  1. CPU inference (no GPU detected)
  2. Low VRAM (system swapping to RAM)
  3. Background processes using GPU
  4. Outdated GPU drivers

Run nvidia-smi to check GPU utilization during generation.

How do I update TRELLIS 2?

cd TRELLIS
git pull origin main
pip install -e .

Always backup your work before updating—new versions may break compatibility.

Troubleshooting Checklist

Before giving up, try these:

  1. Update GPU drivers
  2. Reinstall PyTorch: Ensure CUDA version matches your driver
  3. Check Python version: must be 3.8-3.10
  4. Clear cache then redownload models
  5. Try Docker: Eliminates environment conflicts
  6. Check disk space: Ensure 50GB+ free space

Need Help?

If you're still stuck:

  • GitHub Issues: TRELLIS 2 Repository
  • Discord Community: Join TRELLIS Discord
  • Reddit: r/TRELLIS2 for community support

Ready to Create?

Now that TRELLIS 2 is installed, start generating! Upload a product image, a character design, or an architectural sketch—TRELLIS 2 will turn it into an editable 3D model in seconds.

Pro tip: Start with simple images (solid backgrounds, clear lighting) for best results. Complex scenes may require multiple generations with different seeds.

Happy 3D creating!

Still deciding if TRELLIS 2 is right for you? Compare it with other 3D generation tools in our comprehensive TRELLIS 2 vs Alternatives guide.

trellis2.com

trellis2.com

How to Install Trellis 2: Complete Setup Guide (2025) | 博客