# HoloMotion: a whole-body control policy, and the pipeline that feeds it

> HoloMotion is a Python stack from Horizon Robotics for driving humanoid robots from human motion data, combining a motion tracking policy, a motion conversion layer, a retargeting tool and a deployment path. Its v2 command following mode is still in release preparation, which is the main caveat for anyone planning to use it on hardware.

**HorizonRobotics/HoloMotion** — HoloMotion: A Foundation Model for Whole-Body Humanoid Control

- Repository: https://github.com/HorizonRobotics/HoloMotion
- Stars: 729 · Forks: 52
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/horizonrobotics-holomotion

## A motion tracker, not a complete robot stack

HoloMotion is described as a foundation model for whole-body humanoid control, and the README is careful about which layer of the stack that is. What it provides is a policy that tracks human motion on a humanoid robot, plus the data tooling to produce the motions it tracks.

The distinction matters for adoption. A whole-body controller answers a narrow question: given a reference motion, what joint targets should this robot's legs, arms and torso follow right now. It does not decide what the robot should do, it does not plan, and it does not handle perception or navigation. Those sit above it, and the README's table of projects using HoloMotion shows exactly that pattern. Tsinghua University MARS Lab uses HoloMotion as the tracker for executing generated motions, and Peking University's HumanoidTTT project keeps it frozen as the whole-body tracker for reuse.

So the intended user is a robotics researcher with a humanoid and a policy of their own who does not want to train a low level controller from scratch. The project is Python, distributed under Apache-2.0, and the code is published by Horizon Robotics, the company behind the G1 platform deployments mentioned in the README.

The topic tags say the same thing: humanoid-robot, motion-tracking, whole-body-control, foundation-models and robotics. There is no tag for navigation, perception or task planning, and none is claimed.

## v1 scaled the tracker, and the numbers come from the README

The v1 line is the released, documented capability, and the README describes it as using a reference-conditioned MoE Transformer to track diverse human motions on humanoid robots.

Three properties are claimed, and all three are the project's own statements. Larger: up to 0.4B parameters trained on 2,000+ hours of motion, combining video-derived data with motion capture. Faster: sequence-level training and KV-cache inference, which is the technique behind the claimed throughput. Stronger: generalisation to unseen motion datasets and to real robots without task-specific fine-tuning, as documented in the HoloMotion-1 technical report on arXiv.

The history of the scaling is recorded in the news section. The 2026.05.15 entry says v1.3 scales from 60M to 0.4B parameters and from 80 to 2,000+ hours of motion data, while improving policy inference from roughly 100 to roughly 300 FPS. The 2026.07.16 entry for v1.4 introduces HoloRetarget at more than 3,000 FPS on an RTX 4090 for training data generation, and more than 300 FPS entirely on-robot for teleoperation, together with HoloSMPL for more than ten datasets and devices.

Read those figures as claims rather than measurements. The repository contains no benchmark harness or evaluation output, and the numbers sit in a news section rather than in a results table. The one thing a reader can do is check them against the published technical report, which is linked from the same section.

## v2 unifies sparse commands, and it is not finished

The v2 direction is command following rather than pose tracking, and the headline is that one policy covers several command modes. Pelvis-1 and Keypoint-5, meaning the pelvis plus wrists and ankles, use the same model with selectable control-point masks.

That is a meaningful design choice. Two control modes sharing a single set of weights means the model is not retrained per task, and the mask is what selects which points the policy is asked to satisfy. A separate model per mode would be simpler to reason about but would double the training and maintenance.

The cross-modal extensibility claim needs a caveat. The shared SMPL interface is described as designed to simplify integration of external text-to-motion and music-to-motion models, and the README states plainly that these adapters are not yet included. So the extension point exists and the adapters do not.

The status note is equally plain. v2.0 is in release preparation, real-robot gait and tracking quality are still being refined, especially for pelvis-only control, and validation coverage varies across modes. The news section for 2026.10.12 says v2.0 brings one policy for sparse-to-whole-body control, with initial 1-point and 5-point PICO VR trials completed on G1. A trial is not a validation, and the README says as much.

For planning purposes, treat v1 motion tracking as the usable capability and v2 as a preview you can try if you have the hardware.

## HoloSMPL and HoloRetarget are the parts you will use first

The pipeline is described as one end to end framework, and the README gives it as a chain of documents: motion conversion, retargeting, policy training, simulation evaluation, robot deployment.

The first stage, HoloSMPL, standardises VR, inertial, optical and vision capture into a shared representation. That is the problem it solves, and it is the reason the repository carries a holosmpl/ directory with its own README. Four different capture modalities produce incompatible data, and any motion tracking pipeline needs one canonical form before it can train.

The second stage, HoloRetarget, converts those motions into robot references, for data generation and for live teleoperation. Retargeting is where the human body and the robot body have to be reconciled: different limb lengths, different joint counts, different limits. The repository has a holoretarget/ package and a dedicated document at docs/motion_retargeting.md.

The claim attached to v1.4 is throughput on the order of 3,000 FPS on an RTX 4090 for data generation and 300+ FPS on-robot for teleoperation, which is what makes generation of training data at scale plausible rather than a research curiosity.

The licensing note in the pyproject.toml is worth reading before you build on it. The project metadata says runtime dependencies are installed from the environments/*.yaml files and that the editable package install only registers the repository source in that environment, with the dependencies list left empty on purpose. Installation is therefore an environment file workflow, not a pip install that resolves everything.

## Where the code and the robot hardware meet

The deployment side is specific about hardware, which is the part adopters care about most. The README's table of starting points names a G1 with 29 degrees of freedom and an Orin, a matching deployment image, and PICO or XRoboToolkit for teleoperation. Training or fine-tuning needs labeled robot HDF5 data and GPU resources plus a compatible checkpoint.

The repository layout reflects that structure. There is a deployment/ directory whose Makefile variables point at deployment/unitree_g1_ros2_29dof/src for the robot source and at deployment/holomotion_teleop/tests/ for the teleoperation tests, so the ROS 2 integration and the teleoperation path are separate packages with their own test suites.

There is also a holoboxing/ directory with its own README, described as a local evaluation path for a boxing policy, taking a high-level boxing policy in ONNX, a bundled evaluation image and a compatible GPU. That is a useful reference for how the maintainers expect a downstream policy to be plugged in.

The build and test entry points are a Makefile with lint, format, check and test targets. The test target runs three suites, and each one sets an environment variable to accept the Omniverse end user licence agreement, which is the clearest sign in the repository that the simulation stack is built on Omniverse rather than on a plain physics engine.

```bash
test:
	OMNI_KIT_ACCEPT_EULA=YES $(PYTEST) $(TRAIN_TESTS)
```

The lint and format targets are driven by Ruff, and the ruff configuration in pyproject.toml sets a line length of 79, a py311 target version and a rule set covering pycodestyle errors, pyflakes, import sorting, bugbear, pydocstyle, quote style, warnings and naming.

## The repository, the packaging and the roadmap ahead

The Python packaging is minimal on purpose, and the pyproject.toml shows it. The project name is holomotion at version 2.0.0, the readme is the repository README, and the package discovery includes four packages.

```toml
[tool.setuptools.packages.find]
where = ["."]
include = ["holomotion*", "holoretarget*", "holosmpl*", "holoboxing*"]
```

Version 2.0.0 in the metadata is ahead of the latest tagged release, v1.4.0 from 2026-07-17, which tells you the repository is on the v2 line while the release artefacts lag. Other tagged releases are v1.3.2 from 2026-06-09 and v1.3.1 from 2026-05-29, so the release cadence in 2026 was roughly monthly through the v1 series.

The rest of the tree is the usual research scaffolding plus a few tells. There are environments/ for the dependency files, tests/ for the training tests, thirdparties/ for vendored code, and .gitmodules for submodules. A .gitlab-ci.yml sits next to .githooks/, so continuous integration runs on GitLab while commit hooks live in the repository. AGENTS.md and CLAUDE.md are present, along with NOTICE, LICENSE and deploy.env and train.env files at the root.

The roadmap is stated in the README as a four stage plan: v1 for any pose, released; v2 for any command, in preview; v3 for any embodiment, planned, meaning generalisation across humanoids with different morphologies and actuation; and v4 for any terrain, planned, meaning whole-body control on uneven and dynamic terrain while keeping balance. The v3 and v4 stages are the ones a buyer of a humanoid would eventually care about, and both are explicitly marked as planned rather than as work in progress.

## A pretrained tracker versus your own controller

The alternative to HoloMotion is training your own low level whole-body controller, and the trade-off is between generalisation and control.

Your own controller starts with an advantage: it can be shaped around exactly the motions your robot will perform, and nothing else has to work. If your task is a fixed set of behaviours, the training data can be small, targeted, and consistent, and the failure modes are the ones you designed for. The cost is that every new robot embodiment, every new motion distribution and every change in the action space means new training, and the resulting policy does not transfer.

HoloMotion takes the opposite position. The pretrained tracker is meant to generalise to unseen motion datasets and to real robots without task-specific fine-tuning, and the stated path is toward cross-embodiment generalisation in v3. For a team whose research question is how a policy transfers to a new body, that is the point. The cost is that you inherit someone else's reference conventions, their data processing through HoloSMPL and HoloRetarget, and a checkpoint whose training data you did not collect.

The middle path is what the README recommends, and it is the one to plan around. Start from the v2.0.0 motion tracking checkpoint for simulation and live control, and train or fine-tune only when you need to adapt the policy. The README frames this as no per-user training required, and the table of starting points makes it concrete: an ONNX and config bundle plus a robot NPZ clip for replaying a motion in MuJoCo, the same bundle plus actor weights for evaluating an HDF5 dataset, and labeled robot HDF5 data plus GPU resources when you do need to fine-tune.

The projects listed as using HoloMotion show the intended shape of adoption. Both keep it as the tracker and build something else on top.

## Conclusion

Adopt HoloMotion if you are working on a humanoid and want a pretrained motion tracker to act as the low level execution layer, so that your own policy handles the high level behaviour. Do not adopt it expecting the v2 command following path to be finished, since the README states v2.0 is in release preparation, that real-robot gait and tracking quality are still being refined for pelvis-only control, and that the text-to-motion and music-to-motion adapters are not yet included. Verify first by replaying a reference motion in simulation with the v2.0.0 checkpoint and the ONNX and config bundle, using the Sim2sim guide, before putting anything on a G1 with an Orin.

## FAQ

### What is HoloMotion and who publishes it?

HoloMotion is a foundation model for whole-body humanoid control, published by Horizon Robotics in Python under the Apache-2.0 licence. It provides a policy that tracks human motion on humanoid robots, together with the motion conversion, retargeting, training, evaluation and deployment tooling around it.

### What can I do with HoloMotion without training a policy?

The README points you at the v2.0.0 motion tracking checkpoint for simulation and live control, and says to train or fine-tune only when you need to adapt the policy. Replaying a motion in MuJoCo needs an ONNX and config bundle and a robot NPZ clip, and evaluating a dataset additionally needs actor weights and robot HDF5 data.

### Is HoloMotion v2 ready to use on a robot?

The README states that v2.0 is in release preparation, that real-robot gait and tracking quality are still being refined especially for pelvis-only control, and that validation coverage varies across modes. Initial 1-point and 5-point PICO VR trials have been completed on G1.

## Sources

- [HorizonRobotics/HoloMotion on GitHub](https://github.com/HorizonRobotics/HoloMotion)
- [Issues](https://github.com/HorizonRobotics/HoloMotion/issues)
- [License: Apache-2.0](https://github.com/HorizonRobotics/HoloMotion/blob/master/LICENSE)
- [README](https://github.com/HorizonRobotics/HoloMotion/blob/master/README.md)
- [Releases](https://github.com/HorizonRobotics/HoloMotion/releases)

---

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