User Guide

Installation

GraspKit needs Python 3.10–3.14; the maniskill extra needs 3.10–3.12 and spconv 3.10–3.13. Grasp optimization, rendering, and training need a CUDA GPU.

shell
uv add graspkit
shell
pip install graspkit

From source

shell
uv add git+https://github.com/openrobokit/graspkit.git
shell
pip install git+https://github.com/openrobokit/graspkit.git

To work on GraspKit itself, follow the Development Guide.

PyTorch builds

uv sync installs the dev and pt-cu126 groups by default. The PyTorch groups conflict with each other, so select another one explicitly:

shell
uv sync --no-default-groups --group pt-cu128
GroupWhat it adds
pt-cu126PyTorch + torchvision for CUDA 12.6 (default).
pt-cu118, pt-cu128The same for CUDA 11.8 / 12.8.
pt-cpuCPU-only PyTorch.
devipython, pytest, robot_descriptions (default).

Extras

ExtraWhat it adds
maniskillManiSkill, for simulation, rendering and grasp evaluation (Python 3.10–3.12).
spconvspconv, for the default spconv vision encoder (Python 3.10–3.13).
torchvisiontorchvision, for the rgb_resnet vision encoders.
sam2SAM 2, for the segmentation step of deployment.
xarmretargetingkit[realsense,xarm,ability] + open3d, for the xArm rigs (Python 3.10).
vegaretargetingkit[xarm,ability,dexmate] + pyzmq + open3d, for the Vega humanoid.
data-processcoacd, fast-simplification, for asset processing.

The sam2 extra uses a wheel from a separate index:

shell
uv add "graspkit[sam2]" --index https://jianglongye.github.io/torch_packages_builder
shell
pip install "graspkit[sam2]" --extra-index-url https://jianglongye.github.io/torch_packages_builder
shell
uv run --extra sam2 --extra vega scripts/deploy/deploy.py --help

Assets and credentials

import graspkit downloads nothing. Assets are fetched when the module that needs them is imported: graspkit's scenes, objects and calibration files come from the HuggingFace dataset openrobokit/graspkit into ~/.graspkit/assets/<revision>, and robot URDFs, meshes and collision spheres come from openrobokit/robokit into ~/.robokit/assets/<rev>.

Data and logs live in ~/.graspkit/data and ~/.graspkit/logs, created on import. graspkit.link() symlinks both into the repo for browsing.

  • A .env file with GRASPKIT_S3_ROOT, FSSPEC_S3_ENDPOINT_URL, FSSPEC_S3_KEY and FSSPEC_S3_SECRET is needed only for the _s3 experiments; it is loaded on import.
  • GRASPKIT_EXCLUDED_GPUS lists GPU ids that scripts/launch.py must never use, such as 4,5.
  • graspkit.assets.REVISION pins the asset revision; delete ~/.graspkit/assets/<revision>/.done/ to re-download.

Verify

shell
CUDA_VISIBLE_DEVICES=0 uv run pytest tests/
uv run src/graspkit/examples/grasp_optim/01_basic.py

The example opens a Viser page with optimized xHand grasps. Next: the Quickstart.