Load Trellis2 Apple MLX Pipeline

If you've tried to run Microsoft's TRELLIS on an M-series Mac, you already know the wall: standard TRELLIS.2 is hardcoded for NVIDIA CUDA, the pip install tries to build nvidia wheels that Apple Silicon physically can't run, and you end up six hours deep in a terminal arguing with an LLM. This node is the escape hatch. It's the first node in the Trellis2Apple graph, and its whole job is to get the model loaded so the rest of the chain can work.

Under the hood it's a wrapper around Pedro Naugusto's trellis2-apple, an MLX backend that runs Microsoft's TRELLIS.2 4B image-to-3D model on the Mac's own GPU - MLX instead of CUDA, which is the entire point. The pack is experimental, by dmvvilela, who also maintains the separate ComfyUI-TrellisMac port; keep both installed if you want to compare outputs, but this one is the MLX route.

How it works

The node doesn't hold model weights itself. It locates your trellis2-apple checkout, puts it on sys.path, then builds and caches the MLX pipeline. Finding the checkout is a short priority list: the TRELLIS2_APPLE_PATH environment variable, then the config.json that install.py writes, then a heuristic that looks for a trellis2-apple folder next to the plugin. Leave everything on auto and it reads config.json and loads weights from trellis2-apple/weights/TRELLIS.2-4B. The pipeline is cached keyed by path + weights, so the Generate node downstream doesn't rebuild it every run.

The inputs that matter

Three fields, and for the beginner the answer is "change almost nothing":

• weights_path - defaults to auto, which resolves to the local TRELLIS.2-4B weights. Set it explicitly only if your weights live somewhere unusual.
• reload - false normally. Flip it to true when you swap weights or update the backend and the loader is serving you a stale cached pipeline.
• trellis2_apple_path (optional) - an explicit path to the checkout; entering it saves to config.json so you only do it once.

The single output, pipeline (type TRELLIS2_APPLE_PIPELINE), plugs straight into the pipeline input of Trellis2AppleGenerate.

Installing the real way

The README's path is symlink-plus-installer, not Manager, and there's a reason: install.py is what pulls the MLX, Metal, and o-voxel dependencies into the same Python that launches ComfyUI.

git clone https://github.com/pedronaugusto/trellis2-apple /path/to/trellis2-apple
ln -s /path/to/ComfyUI-Trellis2Apple /path/to/ComfyUI/custom_nodes/ComfyUI-Trellis2Apple
/path/to/ComfyUI/.venv/bin/python custom_nodes/ComfyUI-Trellis2Apple/install.py \
  --trellis2-apple /path/to/trellis2-apple \
  --download-weights
/path/to/ComfyUI/.venv/bin/python custom_nodes/ComfyUI-Trellis2Apple/doctor.py

--download-weights pulls microsoft/TRELLIS.2-4B into trellis2-apple/weights/. The install is heavy - torch, mlx>=0.31, o-voxel, and three Metal packages built from Pedro's forks (mtldiffrast, mtlmesh, mtlgemm) - so budget some compile time. Then restart ComfyUI.

Where people get burned

• Wrong Python. Run install.py and doctor.py with the exact interpreter that launches ComfyUI (.venv/bin/python above), or the imports quietly go into the wrong environment and the loader errors at runtime.
• "does not look like trellis2-apple." The checker wants the real checkout with mlx_backend/, trellis2/, and o-voxel/. Point it at the right folder, or set TRELLIS2_APPLE_PATH.
• Missing weights. doctor.py warns "local weights not found" if weights/TRELLIS.2-4B/pipeline.json isn't there. Re-run with --download-weights.
• transformers 5+. The backend pins transformers>=4.40,<5; if your ComfyUI env already has 5.x, trellis2-apple can choke. doctor.py flags it and install.py will downgrade.
• Gated models. The backend needs facebook/dinov3-... and briaai/RMBG-2.0 from Hugging Face - hf auth login if doctor.py says no token.
• Not a Mac. This targets Apple Silicon (arm64). On x86 you're installing a warning.

One honest note: this is a 4B model running locally, so it wants a machine with serious unified memory. The community verdict on the Apple-port family is roughly "24 GB before it stops crashing" - treat that as the ballpark floor for this class of tool.