Install AI World Model HY-World 2.0 Guide

AI world model on your own box means more than a one-minute clip: persistent 3D Gaussian / mesh assets you open in a viewer or engine. Tencent’s HY-World 2.0 is that stack – WorldMirror 2.0 open-sourced April 16, 2026, world-gen code May 18, 2026, product line tagged 2.1 as of July 2026, per the official GitHub news track. Tencent-Hunyuan/HY-World-2.0

Deploy path only. System floors, copy-paste install for the documented tree, Gradio verify, the errors people hit, then upgrade and cleanup. Skip the Dreamer history lecture. Later: 3DGS pipelines and multi-view recon tooling.

What you’re installing (and what you’re not)

Text, single image, multi-view, or video in → 3D worlds out. The HY-World 2.0 report (arXiv:2604.14268) wires that through panorama (HY-Pano 2.0), trajectory planning (WorldNav), expansion (WorldStereo 2.0), and composition (WorldMirror 2.0 + 3DGS). Day-one local win is WorldMirror 2.0: one forward pass → depth, normals, cameras, points, 3DGS attributes.

Weights live on Hugging Face tencent/HY-World-2.0. Cloud try-out: 3d.hunyuan.tencent.com/sceneTo3D.

Pro tip: Reconstruction first. Full world generation piles on git submodules, a navmesh build, a VLM server for trajectories, and multi-billion-parameter siblings. Gradio reconstruct green = CUDA / torch / gsplat already proven.

System requirements for this AI world model

As of community writeups collected beside the Model Zoo numbers: WorldMirror recon often fits roughly 6-16 GB VRAM on small scenes, with 12-24 GB feeling less fragile; 32-frame batches on 16 GB still OOM a lot. Full gen is another machine class – WorldMirror is ~1.2B; the stereo/pano siblings jump an order of magnitude. Clore’s Hunyuan World 2 notes track the same split.

Read the Tencent HY-WORLD 2.0 Community License before the download finishes. It does not apply in the EU, UK, or South Korea. That’s not fine print after a successful splat – it’s a territory wall at the door. Weird place for a 3D pipeline to stop you, and it still does.

Download and staged install (HY-World 2.0)

Clone the official tree. There is no separate “v2.1 open-source tarball”; 2.1 is the product track. Public code stays in this repo.

git clone https://github.com/Tencent-Hunyuan/HY-World-2.0
cd HY-World-2.0

conda create -n hyworld2 python=3.11.15
conda activate hyworld2

pip install -r requirements.txt

requirements.txt pins torch==2.7.1 and torchvision==0.22.1. Driver/toolkit skew? Fix CUDA 12.8 alignment first – don’t shotgun random torch wheels.

gsplat: fork vs official

# Preferred once for recon + worldgen (custom MaskGaussian fork)
cd hyworld2/worldgen/third_party/gsplat_maskgaussian
pip install -e . --no-build-isolation
cd ../../../../

# Recon-only fallback
# pip install git+https://github.com/nerfstudio-project/gsplat.git

One path. Mix wheels and you get the silent break that wastes an afternoon – imports succeed, training/recon paths disagree later.

FlashAttention (install exactly one path)

# Hopper: FlashAttention-3 from source
git clone https://github.com/Dao-AILab/flash-attention.git
cd flash-attention/hopper
python setup.py install
cd ../../
rm -rf flash-attention

# Simpler FA2 (most consumer boxes)
pip install flash-attn --no-build-isolation

Hopper FA3 on Windows / non-Hopper GPUs fails constantly. FA2 is the boring path that works. Or patch attention imports to PyTorch SDPA – WorldMirror still runs, just slower. Don’t leave half-built hopper trees on PATH.

Optional: world generation extras

pip install --no-build-isolation -r requirements_git.txt
git submodule update --init --recursive
cd hyworld2/worldgen/third_party/navmesh
pip install . --no-build-isolation
cd ../../../../

HY-Pano sits under hyworld2/panogen/ with its own README (separate conda pin in places). Trajectory stages want a live VLM (vLLM + Qwen-VL class) and multi-GPU for sane throughput. Don’t block first verify on that.

First-time configuration and verify

Smallest path that proves the stack: HF login if gated/rate-limited, then Gradio.

huggingface-cli login
# or: export HF_TOKEN=...

python -m hyworld2.worldrecon.gradio_app

Open whatever URL the process prints – community boxes often land on http://127.0.0.1:8081. A few multi-view images or a short examples/ clip → reconstruct → depth / normals / points / 3DGS preview. First run pulls WorldMirror into the HF cache (~5.05 GB folder on the Hub tree).

from hyworld2.worldrecon.pipeline import WorldMirrorPipeline

pipeline = WorldMirrorPipeline.from_pretrained(
 "tencent/HY-World-2.0",
 # subfolder defaults to HY-WorldMirror-2.0 per docs
)
result = pipeline("path/to/images")

CLI single GPU:

python -m hyworld2.worldrecon.pipeline --input_path path/to/images

Multi-GPU only when view count keeps up:

torchrun --nproc_per_node=2 -m hyworld2.worldrecon.pipeline 
 --input_path path/to/images --use_fsdp --enable_bf16

The catch: under FSDP / torchrun, input image count must be ≥ nproc_per_node. Eight ranks with four photos won’t “just shard” – README states the precondition outright. Add views or drop ranks.

There’s a quiet satisfaction the first time the browser shows a coherent splat instead of another infinite video loop. Then optional checkpoints fill the disk and you’re back to capacity planning.

Common install errors and fixes

• flash-attn / ninja / CUDA_HOME mismatch – Toolkit on 12.8, set CUDA_HOME, prefer pip install flash-attn --no-build-isolation, or SDPA fallback.
• gsplat compile fails (Windows MSVC / arch list) – VS C++ build tools, SM arch list for your GPU, editable install with --no-build-isolation on the vendored fork.
• CUDA OOM – Fewer frames, lower input resolution, enable_bf16, disable unused heads via API (camera / depth / normal / points / gs), or FSDP only with enough views.
• Multi-GPU hang / assert – Same image-count rule as above; otherwise single GPU.
• torch / driver skew – Pin stays 2.7.1; cu124 wheels on a 12.8-only host is a self-own.

Gradio binds but reconstruct spins forever? Watch nvidia-smi before blaming the UI.

Upgrade, migration, uninstall

Open weights follow GitHub main on HY-World-2.0 – not a classic SemVer app binary.

cd HY-World-2.0
git pull
conda activate hyworld2
pip install -r requirements.txt
# rebuild gsplat / navmesh if third_party changed

Clear stale HF cache only when a weight hash changed and loads look corrupt. Product “2.1” cloud flags may not map 1:1 locally – read repo release notes before assuming parity.

conda deactivate
conda env remove -n hyworld2
rm -rf HY-World-2.0
# optional: rm -rf ~/.cache/huggingface/hub/models--tencent--HY-World-2.0

Anything gsplat / flash-attn you installed outside the env will poison the next project. Remove it.

FAQ

Is HY-World 2.0 the same as a video world model like Genie or Cosmos?

No. Those emit pixel video. HY-World 2.0 bakes editable 3DGS/mesh assets you can import later.

What’s the smallest GPU that can run the AI world model locally?

WorldMirror recon only – see the requirements band above. Full stereo/pano gen is not that card.

Do I need the custom gsplat fork?

Vendored gsplat_maskgaussian when you care about worldgen training with MaskGaussian pruning – that’s the docs default for the five-stage gen trainer. Recon-only can stay on upstream nerfstudio gsplat. Switching mid-project is a rebuild, not a one-line pip flag. People assume “gsplat is gsplat”; the fork is where MaskGaussian actually lives.

Next: clone, create hyworld2, finish FA2 + gsplat, run python -m hyworld2.worldrecon.gradio_app, reconstruct one sample folder – before worldgen or a rented multi-GPU box.