Guide · Open source
How to use TRELLIS: install, load models and generate 3D assets
Updated · written with AI from the project's own documentation and checked against our catalogue data
TRELLIS is an open-source research model from Microsoft that turns a text prompt or an image into a 3D object, which can be exported as a mesh, 3D Gaussians or a radiance field. It is built for people who are comfortable with Python and the command line and have an NVIDIA GPU. This guide covers the requirements, installation, loading the pretrained models and what you can do with the output.
TRELLISmicrosoft/TRELLIS · ★ 14.2k · MIT Install options & downloads Quick start
- 1Check your hardware. Confirm you have Linux, an NVIDIA GPU with at least 16GB of memory, and a CUDA Toolkit version such as 11.8 or 12.2.
- 2Clone the repository. Run git clone with --recurse-submodules, then cd into the TRELLIS folder.
- 3Run the setup script. Run the setup.sh command with the flags listed in the README to create the trellis conda environment and install dependencies.
- 4Load a pretrained model. Call TrellisImageTo3DPipeline.from_pretrained with microsoft/TRELLIS-image-large to load the image-to-3D model from Hugging Face.
- 5Generate a 3D asset. Open and run example.py to generate a 3D asset from an input image.
- 6Export the output. Choose the output format you need, such as a mesh, 3D Gaussians or a radiance field.
Check the requirements before you install
TRELLIS needs an NVIDIA GPU with at least 16GB of memory. The README says this is necessary, and the code has been verified on A100 and A6000 GPUs.
The code is tested only on Linux. The README links to an issue for Windows setup but says that path is not fully tested.
- Operating system: Linux (tested)
- GPU: NVIDIA with at least 16GB memory
- CUDA Toolkit: tested with 11.8 and 12.2, needed to compile some submodules
- Conda: recommended for managing dependencies
- Python: 3.8 or higher
Clone the repository and install dependencies
Clone the repository with its submodules, then enter the project folder. The submodules are required, so do not skip the --recurse-submodules flag.
The setup script creates a conda environment named trellis by default and installs the listed components. The install can take a while because there are many dependencies. If it fails, the README suggests installing the dependencies one flag at a time.
If you have several CUDA Toolkit versions installed, set PATH to the correct one before running the script. The README gives the example export PATH=/usr/local/cuda-11.8/bin:$PATH. Run node setup.sh --help to see all options.
- Remove --new-env if you want to use an existing conda environment.
- Remove --flash-attn and set ATTN_BACKEND to xformers if your GPU does not support flash-attn, such as NVIDIA V100.
- Use --demo to install all dependencies for the demo.
git clone --recurse-submodules https://github.com/microsoft/TRELLIS.git
cd TRELLIS
. ./setup.sh --new-env --basic --xformers --flash-attn --diffoctreerast --spconv --mipgaussian --kaolin --nvdiffrastLoad a pretrained model
The models are hosted on Hugging Face and can be loaded by repository name. The README lists TRELLIS-image-large (1.2B parameters) for image-to-3D, and TRELLIS-text-base, TRELLIS-text-large and TRELLIS-text-xlarge for text-to-3D.
The README recommends the image-conditioned version for better performance. It also notes that all VAEs are included in the TRELLIS-image-large repository. You can also download the model files and load them from a local folder, keeping the folder structure intact.
- TRELLIS-image-large: large image-to-3D model, 1.2B parameters
- TRELLIS-text-base: base text-to-3D model, 342M parameters
- TRELLIS-text-large: large text-to-3D model, 1.1B parameters
- TRELLIS-text-xlarge: extra-large text-to-3D model, 2.0B parameters
TrellisImageTo3DPipeline.from_pretrained("microsoft/TRELLIS-image-large")Run the minimal example
The repository includes example.py, a minimal script that loads the pretrained models and generates a 3D asset. Open it to see the full flow. The README shows the top of the script, where the attention backend and the SPCONV_ALGO environment variable are set.
The README notes that for text-to-3D, it is better to first generate an image with a text-to-image model and then use the image-based TRELLIS model. Text-conditioned models are less creative and detailed due to data limitations.
- example.py: minimal image-to-3D example
- example_text.py: text-to-3D example
- example_variant.py: generates variants of an asset
- app.py and app_text.py: Gradio demos
os.environ['SPCONV_ALGO'] = 'native'Export the output in different formats
One of TRELLIS's main features is decoding the same structured latent into several output types. The README lists radiance fields, 3D Gaussians and meshes. Gaussian export is available in app.py and example.py.
The project also supports local editing of a generated asset and generating variants of the same object.
- Meshes
- 3D Gaussians
- Radiance Fields
What people use it for
- Researchers exploring text- or image-to-3D generation
- Developers with an NVIDIA GPU prototyping 3D asset pipelines in Python
- Creators who want a quick 3D starting point from a single image
- Exporting one generated asset in several formats
Frequently asked questions
Does TRELLIS run on Windows?
The README says the code is currently tested only on Linux. It links to an issue for Windows setup, but notes that this path is not fully tested.
How much GPU memory does TRELLIS need?
The README says an NVIDIA GPU with at least 16GB of memory is necessary. The code has been verified on NVIDIA A100 and A6000 GPUs.
Is TRELLIS free to use?
The repository is released under the MIT licence, as listed on the project page. Check the licence file in the repo for the full terms.
Can I use TRELLIS without an NVIDIA GPU?
The README requires an NVIDIA GPU with at least 16GB of memory, so the project is not designed for other hardware. If your GPU does not support flash-attn, the README suggests using xformers instead.
Is there a no-code version of TRELLIS?
The project is a research codebase run from the command line and Python. The README links to a Hugging Face Live Demo and includes Gradio demos in app.py and app_text.py, but it does not describe a polished no-code tool.
What are the alternatives to TRELLIS?
Comparable projects listed for this item are Shap-E, Point-E and Zero123. Compare them on output formats, hardware needs and licence before choosing one.
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 suits researchers and Python developers with a Linux machine and an NVIDIA GPU with at least 16GB of memory who want to prototype image- or text-to-3D generation and export assets in several formats. It is a poor fit for anyone without that hardware, anyone on Windows who needs a tested setup, or anyone who wants a polished no-code tool.
Install options & downloads