Installation#

Installation of ManiSkill is extremely simple, you only need to run a few pip installs

# install the package and a version of torch that is compatible with your system
pip install --upgrade mani_skill torch

We also provide a more frequently updated nightly version updated daily whenever there are changes to ManiSkill:

pip install mani_skill-nightly torch

For the majority of MacOS users there is a bit more setup needed for installing the Vulkan driver which is required, please see the MacOS Installation page for details.

Note

While state-based simulation does not require any additional dependencies, a GPU with the Vulkan driver installed is required to enable rendering in ManiSkill. See here for how to install and configure Vulkan on Ubuntu. Furthermore we currently best support linux machines with NVIDIA GPUs, with limited support on other systems, see the system requirements section for details.

The rigid-body tasks, powered by SAPIEN, are ready to use after installation. Test your installation:

# Run an episode (at most 50 steps) of "PickCube-v1" (a rigid-body task) with random actions
# Or specify an task by "-e ${ENV_ID}"
python -m mani_skill.examples.demo_random_action

A docker image is also provided on Docker Hub called maniskill/base and its corresponding Dockerfile.

Once you are done here, you can head over to the quickstart page to try out some live demos and start to program with ManiSkill.

There are also 2 environment variables that you may want to set. There are many assets, demonstration datasets etc. that are not downloaded by default. Modify MS_ASSET_DIR to the directory where you want to save all the data for ManiSkill, which by default is ~/.maniskill/data.

export MS_ASSET_DIR=path/to/where/to/save/all/mani_skill_data

You can also do the following to skip the prompt to download the assets, meaning if you run code that needs access to assets that are not found, it will no longer prompt you to download them.

export MS_SKIP_ASSET_DOWNLOAD_PROMPT=1

System Support#

We currently best support Linux based systems. There is limited support for windows and no support for MacOS at the moment. We are working on trying to support more features on other systems but this may take some time. Most constraints stem from what the SAPIEN package is capable of supporting.

System / GPU

CPU Sim

GPU Sim

Rendering

Linux / NVIDIA GPU

✅

✅

✅

Windows / NVIDIA GPU

✅

❌

✅

Windows / AMD GPU

✅

❌

✅

WSL / Anything

✅

❌

❌

MacOS / Anything

✅

❌

✅

Troubleshooting#

Vulkan#

Ubuntu#

To install Vulkan on Ubuntu:

sudo apt-get install libvulkan1

To test your installation of Vulkan:

sudo apt-get install vulkan-tools
vulkaninfo

If vulkaninfo fails to show the information about Vulkan, please check whether the following files exist:

  • /usr/share/vulkan/icd.d/nvidia_icd.json

  • /usr/share/glvnd/egl_vendor.d/10_nvidia.json

  • /etc/vulkan/implicit_layer.d/nvidia_layers.json (optional, but necessary for some GPUs like A100)

If /usr/share/vulkan/icd.d/nvidia_icd.json does not exist, try to create the file with the following content:

{
    "file_format_version" : "1.0.0",
    "ICD": {
        "library_path": "libGLX_nvidia.so.0",
        "api_version" : "1.2.155"
    }
}

If /usr/share/glvnd/egl_vendor.d/10_nvidia.json does not exist, you can try sudo apt-get install libglvnd-dev. 10_nvidia.json contains the following content:

{
    "file_format_version" : "1.0.0",
    "ICD" : {
        "library_path" : "libEGL_nvidia.so.0"
    }
}

If /etc/vulkan/implicit_layer.d/nvidia_layers.json does not exist, try to create the file with the following content:

{
    "file_format_version" : "1.0.0",
    "layer": {
        "name": "VK_LAYER_NV_optimus",
        "type": "INSTANCE",
        "library_path": "libGLX_nvidia.so.0",
        "api_version" : "1.2.155",
        "implementation_version" : "1",
        "description" : "NVIDIA Optimus layer",
        "functions": {
            "vkGetInstanceProcAddr": "vk_optimusGetInstanceProcAddr",
            "vkGetDeviceProcAddr": "vk_optimusGetDeviceProcAddr"
        },
        "enable_environment": {
            "__NV_PRIME_RENDER_OFFLOAD": "1"
        },
        "disable_environment": {
            "DISABLE_LAYER_NV_OPTIMUS_1": ""
        }
    }
}

More discussions can be found here.

The following errors can happen if the Vulkan driver is broken. Try to reinstall it following the above instructions.

  • RuntimeError: vk::Instance::enumeratePhysicalDevices: ErrorInitializationFailed

  • Some required Vulkan extension is not present. You may not use the renderer to render, however, CPU resources will be still available.

  • Segmentation fault (core dumped)

If you still have some issues, you can check the NVIDIA drivers. First run

ldconfig -p | grep libGLX_nvidia

If libGLX_nvidia.so is not found, then it is likely that you have installed an incorrect driver. To get the right driver on linux, it is recommended to install nvidia-driver-xxx (do not use the ones with server in the package name) and to avoid using any other method of installation like a runfile

MacOS#

See the MacOS Installation page for more details.

Uninstallation#

If mani_skill is installed through pip, run pip uninstall mani-skill.

Note

There might exist some cache files (e.g., compiled shared library files, convex meshes generated by SAPIEN) generated in the package directory. There may also be data downloaded to your ~/.maniskill directory. To fully uninstall mani_skill, please remove those files manually.