# UniRig: automatic rigging for 3D models, and the successor already queued above it

> A SIGGRAPH 2025 research release that predicts 3D skeleton hierarchies and skinning weights with an autoregressive transformer, distributed as one checkpoint and one training script.

**VAST-AI-Research/UniRig** — [SIGGRAPH 2025] One Model to Rig Them All: Diverse Skeleton Rigging with UniRig

- Repository: https://github.com/VAST-AI-Research/UniRig
- Website: https://zjp-shadow.github.io/works/UniRig/
- Stars: 1,804 · Forks: 176
- Language: Python
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/vast-ai-research-unirig

## Rigging is the step between a mesh and an animation

A mesh is a bag of vertices with no joints. Before it can bend, it needs a skeleton, a hierarchy of bones, and per-vertex weights saying how much each bone moves each vertex. Doing that by hand in Blender is slow, and it is the step that sits between an artist finishing a model and an animator being able to pose it. UniRig attacks exactly that step, and it is worth understanding why the problem is hard before looking at the code.

The difficulty is that the right answer is not determined by geometry alone. A four-legged animal, a piece of furniture and a bipedal character all need different hierarchies, and a single mesh can legitimately be rigged several valid ways. A model that predicts one canonical skeleton for everything tends to produce anatomically wrong results on the minority of shapes.

The SIGGRAPH 2025 paper behind this repository takes the position that the variety can be handled by making the model autoregressive over a structured representation of the skeleton itself, rather than by writing a separate heuristic per asset category. The repository description states the goal plainly: one model to rig them all. The topic tags on the repository are animation, auto-rigging, autoregressive and computer-graphics, which matches a research codebase rather than a shipping tool.

## Two stages, one checkpoint and a bone-point cross attention

The README describes the system as two stages. Stage one is skeleton prediction: an autoregressive transformer, styled after GPT, emits a topologically valid hierarchy using what the authors call Skeleton Tree Tokenization. Stage two is skinning weight and attribute prediction, where a Bone-Point Cross Attention mechanism reads the predicted skeleton alongside the input mesh geometry and assigns each vertex its weights.

That second stage is the interesting design choice. Instead of treating skinning as a per-vertex regression that has to guess which bone it is near, the cross attention lets each mesh point query the bone set directly. Bone attributes, such as stiffness values used by physics-based secondary motion, are predicted through the same mechanism, which is why the feature list groups them together.

What ships and what does not is marked carefully in the README's feature list. Automated skeleton generation and automated skinning prediction are both marked available in the current release. Bone attribute prediction is marked as coming soon, with a clock emoji rather than a version number, so anyone planning on physics-driven secondary motion should not expect it. The framework is also described as designed to potentially support iterative refinement workflows, which is future tense and should be read that way.

## Installing means pinning a CUDA-specific dependency set

The installation is five numbered steps and it is specific about versions. Python 3.11 is the prerequisite and PyTorch is tested from 2.3.1 upward. The clone and environment setup are unremarkable:

```bash
git clone https://github.com/VAST-AI-Research/UniRig
cd UniRig
```

```bash
conda create -n UniRig python=3.11
conda activate UniRig
```

The dependency step is where projects like this usually lose people, and the README does not pretend otherwise. Two of the installs need a placeholder you fill in for your own CUDA version, and the README warns that flash_attn will probably fail:

```bash
python -m pip install torch torchvision
python -m pip install -r requirements.txt
python -m pip install spconv-{you-cuda-version}
python -m pip install torch_scatter torch_cluster -f https://data.pyg.org/whl/torch-{your-torch-version}+{your-cuda-version}.html --no-cache-dir
python -m pip install numpy==1.26.4
```

The requirements file pins transformers at 4.51.3 and bpy at 4.2, which matters because the repository ships a `blender/` directory and depends on Blender's Python API for part of its mesh handling. The rest of the file is a mix of training and geometry libraries:

```text
transformers==4.51.3
python-box
einops
omegaconf
pytorch_lightning
flash_attn
trimesh
open3d
pyrender
wandb
```

The presence of pytorch_lightning and wandb in the same list tells you the repository is built to be trained, not just to run inference.

## Reading the tree to find the pipeline

The top level is short enough to read as a map. There is `run.py` as the obvious entry point, `src/` for the implementation, `configs/` for experiment configuration, `datalist/` for dataset manifests, `launch/` for distributed launch scripts, `blender/` for Blender-side code, `examples/` for sample assets, and an `assets/` directory that holds the teaser images the README embeds.

The root also carries `.gitattributes` and `.gitignore` alongside a `LICENSE` file. GitHub reports the repository license as MIT, and the presence of a LICENSE file at the root agrees with that, so the licensing picture here is straightforward: you may use, modify and redistribute the code, including commercially, with the notice retained. The checkpoints and the datasets are a separate question, since those are distributed through Hugging Face rather than through this repository.

The repository was last pushed on 2026-06-04 and is not archived. Open issues sit at 28, which for a research repository of this size suggests an active but not overwhelming support load. The default branch is `main` and the language field reports Python.

## The released checkpoint is not the one behind the paper numbers

This is the single most important thing to understand before you plan around UniRig, and the README is upfront about it in a section headed current release status and roadmap. What is available now is the implementation code for skeleton and skinning prediction, the training code, the Rig-XL and VRoid datasets used in the paper, and a checkpoint trained on Articulation-XL2.0.

The planned future release is described as the full UniRig model checkpoints, skeleton and skinning, trained on Rig-XL/VRoid, replicating the paper's main results. So the weights you can download today are not the weights that produced the accuracy figures in the paper. Both statements are in the same README, and they are not in conflict, they are a sequencing decision. The consequence for a reader is concrete: if you are evaluating whether UniRig hits the numbers in the abstract, you are not running that configuration yet.

The dataset release is also more than a download. The README notes that 31 broken models were filtered out of the training dataset and states that this does not affect the performance of the final model. That is a small, credible detail: it means the released data is the cleaned version rather than the raw version, and anyone reproducing training runs should use the filtered set.

Both datasets and the checkpoint are published under the VAST-AI organization on Hugging Face, with the model at a namespace of the same name as this repository.

## The README already recommends a successor

The most prominent thing on the page is an announcement box at the top, above the project description, announcing SkinTokens as the powerful successor to UniRig. The claims are specific: SkinTokens unifies skeleton prediction and skinning into a single autoregressive sequence through learned discrete skin tokens, and adds reinforcement learning plus an efficient skinning compression module, with reported gains of 98% to 133% in skinning accuracy and 17% to 22% in bone prediction over state-of-the-art baselines.

Those are the authors' own numbers for the successor, so they should be read as claims to check rather than established results. What matters for someone deciding what to build on is the direction of travel. UniRig uses separate stages for skeleton prediction and skinning. SkinTokens is explicitly about removing that split. Adopting UniRig means adopting an architecture its own authors have publicly moved past.

There is also a curious naming detail worth knowing if you go looking for prior art: the SkinTokens announcement sits directly above the section describing the current roadmap, and the Skeleton Tree Tokenization scheme in UniRig is the earlier idea that discrete skin tokens generalize.

The research context is Tsinghua University with Tripo, and the project has a GitHub Pages site, a technical blog post, and the arXiv paper at 2504.12451. Those external pages carry the architecture detail and benchmark tables that the repository itself does not.

## Conclusion

UniRig is worth an afternoon if your pipeline has a queue of meshes waiting for a skeleton, because it collapses two hand steps into one checkpoint and keeps the datasets public. It is not a drop-in for a production character pipeline: the released weights are not the weights behind the paper's headline numbers, bone attribute prediction is still marked as coming, and the README already points readers at a successor project. Treat it as a research checkpoint you evaluate against your own meshes, start from the Articulation-XL2.0 model on Hugging Face, and read requirements.txt before you promise anyone a reproducible environment.

## FAQ

### What does UniRig actually automate in a 3D pipeline?

It automates the two steps that turn a raw mesh into something animatable: predicting a skeleton hierarchy and predicting the per-vertex skinning weights that bind vertices to bones. The README marks both as available in the current release, while bone attribute prediction for physics is still listed as coming.

### Can I use the published UniRig checkpoint to reproduce the paper's results?

Not directly. The README says the currently published checkpoint was trained on Articulation-XL2.0, and that the checkpoints trained on Rig-XL and VRoid to replicate the paper's main results are planned for a future release. So the available weights are a different training configuration from the one in the paper.

### Is UniRig licensed for commercial use?

The repository is reported under the MIT license and carries a LICENSE file at its root, so the code itself is permissive. The model checkpoints and datasets are published separately on Hugging Face, so their terms should be checked where they are actually hosted.

### Should I start with UniRig or the newer SkinTokens project?

The UniRig README itself announces SkinTokens as its successor and points readers there. If you only need a rig today and want the documented checkpoint and dataset releases, UniRig is the more complete starting point. If you are designing an architecture rather than evaluating one, SkinTokens is the direction the authors describe themselves as moving in.

## Sources

- [Issues](https://github.com/VAST-AI-Research/UniRig/issues)
- [License: MIT](https://github.com/VAST-AI-Research/UniRig/blob/main/LICENSE)
- [Project website](https://zjp-shadow.github.io/works/UniRig/)
- [README](https://github.com/VAST-AI-Research/UniRig/blob/main/README.md)
- [VAST-AI-Research/UniRig on GitHub](https://github.com/VAST-AI-Research/UniRig)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vast-ai-research-unirig