Environment:Haosulab ManiSkill Python SAPIEN Core

Knowledge Sources	ManiSkill SAPIEN
Domains	Robotics_Simulation, Reinforcement_Learning
Last Updated	2026-02-15 08:00 GMT

Overview

Python 3.9+ environment with SAPIEN 3.x physics engine, Gymnasium 0.29.1+, PyTorch, and core manipulation skill dependencies for the ManiSkill3 benchmark.

Description

This environment defines the core software stack required to run any ManiSkill task. It is built around the SAPIEN physics simulator (version 3.x) with platform-specific builds for Linux, Windows, and macOS. The stack includes Gymnasium for the RL interface, PyTorch for tensor operations and GPU acceleration, NumPy for array processing, and H5PY for trajectory storage. Additional utilities include pytorch_kinematics for robot IK, trimesh for mesh processing, and imageio with ffmpeg for video recording.

Usage

This environment is required for all ManiSkill workflows: RL training, imitation learning, custom task development, motion planning demo generation, and sim2real deployment. Every Implementation page in the ManiSkill wiki requires this environment as a prerequisite.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu 20.04+), Windows 10+, or macOS 12+	Linux is the primary supported platform
Hardware	CPU with SSE4.2 support	GPU optional for CPU-only simulation (num_envs=1)
Python	>= 3.9	Specified in setup.py:96
Disk	2GB+ for package, 10GB+ for assets	Assets stored in ~/.maniskill by default

Dependencies

System Packages

`ffmpeg` (required by imageio for video recording)
`git` (required by GitPython for version tracking)

Python Packages

`numpy` >= 1.22
`scipy`
`dacite`
`gymnasium` >= 0.29.1
`h5py`
`pyyaml`
`tqdm`
`GitPython`
`tabulate`
`transforms3d`
`trimesh`
`imageio`
`imageio[ffmpeg]`
`pytorch_kinematics` == 0.7.6
`nvidia-ml-py`
`tyro` >= 0.8.5
`huggingface_hub`
`IPython`

Platform Specific Packages

Linux: `sapien` >= 3.0.0
Windows: `sapien` >= 3.0.0.b1
macOS: `sapien` >= 3.0.2

Credentials

The following environment variables may be set:

`MS_ASSET_DIR`: Override default asset directory (default: `~/.maniskill`). Controls where downloaded assets and demos are stored.
`MS_SKIP_ASSET_DOWNLOAD_PROMPT`: Set to `"1"` to skip interactive download prompts (useful for CI/CD).
`MS_RENDERER_LOG_LEVEL`: Set SAPIEN renderer log level (default: `"warn"`).

Quick Install

# Install ManiSkill with all core dependencies
pip install mani_skill

# Or install from source
git clone https://github.com/haosulab/ManiSkill.git
cd ManiSkill
pip install -e .

# For development
pip install -e ".[dev]"

Code Evidence

Python version requirement from `setup.py:96`:

python_requires=">=3.9"

SAPIEN platform-specific requirements from `setup.py:50-52`:

"sapien>=3.0.0;platform_system=='Linux'",
"sapien>=3.0.0.b1;platform_system=='Windows'",
"sapien>=3.0.2;platform_system=='Darwin'",

Asset directory configuration from `mani_skill/__init__.py:14-25`:

ASSET_DIR = Path(
    os.path.join(
        os.getenv("MS_ASSET_DIR", os.path.join(os.path.expanduser("~"), ".maniskill")),
        "data",
    )
)
DEMO_DIR = Path(
    os.path.join(
        os.getenv("MS_ASSET_DIR", os.path.join(os.path.expanduser("~"), ".maniskill")),
        "demos",
    )
)

SAPIEN render system version detection from `mani_skill/render/version.py:2-8`:

SAPIEN_RENDER_SYSTEM = "3.0"
try:
    from sapien.wrapper.scene import get_camera_shader_pack
    SAPIEN_RENDER_SYSTEM = "3.1"
except:
    pass

Common Errors

Error Message	Cause	Solution
`ImportError: pytorch_kinematics_ms not installed`	pytorch_kinematics package missing	`pip install pytorch_kinematics==0.7.6`
`ImportError: svgpathtools not installed`	Optional dep for DrawSVG task	`pip install svgpathtools`
`mani_skill is not installed with git`	GitPython cannot find .git directory	Install from git clone, not pip tarball
Asset download prompt blocks CI	Interactive prompt in headless mode	Set `MS_SKIP_ASSET_DOWNLOAD_PROMPT=1`

Compatibility Notes

macOS: SAPIEN on macOS requires version >= 3.0.2 and may need manual installation from the nightly release wheel. CPU-only rendering is forced on macOS (no CUDA rendering support).
Windows: SAPIEN on Windows uses a beta build (>= 3.0.0.b1). The `collision_stack_size` GPU parameter may not be supported.
Linux: Full support for GPU simulation and rendering. This is the primary development platform.
Sphinx Docs: Documentation requires sphinx == 6.2.1 specifically; sphinx 7 is not compatible.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment