Installation

There are two steps to install iGibson, the Interactive Gibson Environment, on your computer.

First, you need to install the simulation environment. This may require installing additional dependencies. Then, you need to download the assets: models of the robotic agents, the interactive objects and 3D reconstructed real-world large environments for your agents to train.

Installing the Environment

System Requirements

The minimum system requirements are the following:

Linux
- Ubuntu 16.04
- Nvidia GPU with VRAM > 6.0GB
- Nvidia driver >= 384
- CUDA >= 9.0, CuDNN >= v7
- CMake >= 2.8.12 (can install with pip install cmake)
- g++ (GNU C++ compiler)
- libegl-dev (Debian/Ubuntu: vendor neutral GL dispatch library – EGL support)
Windows
- Windows 10
- Nvidia GPU with VRAM > 6.0GB
- Nvidia driver >= 384
- CUDA >= 9.0, CuDNN >= v7
- CMake >= 2.8.12 (can install with pip install cmake)
- Microsoft Visual Studio 2017 with visual C++ tool and latest Windows 10 SDK
Mac OS X
- Tested on several versions (10.15, 11.6, …)
- PBR features not supported
- CMake >= 2.8.12 or CMake >= 2.17 for M1-chip (do NOT install with pip install cmake, but system-wide for example with Homebrew)

Other system configurations may work, but we haven’t tested them extensively and we probably won’t be able to provide as much support as we want.

Installing dependencies in Linux machines

As most Python packages, we recommend to install iGibson in a virtual environment. We suggest to use Conda instead of a standard virtual environment. To setup anaconda with the right dependencies, run the following as your user account (not as root/superuser):

# Install miniconda
curl -LO http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh
bash Miniconda-latest-Linux-x86_64.sh
rm Miniconda-latest-Linux-x86_64.sh

# Add conda to your PATH
echo "export PATH=$HOME/.miniconda/bin:$PATH" >> .bashrc 

# Update conda and create a virtual environment for iGibson
conda update -y conda
conda create -y -n igibson python=3.8
conda activate igibson

Careful, this may change your GPU drivers!

There are several system dependencies to correctly run iGibson on Linux, mostly related to Nvidia drivers and Cuda. In case your system is a clean Ubuntu 20.04, you can run the following commands as root/superuser to install all required dependencies:

Click to expand the code to install the dependencies including Nvidia drivers in headless mode to use for example in a cluster:

# Add the nvidia ubuntu repositories
apt-get update && apt-get install -y --no-install-recommends \
    gnupg2 curl ca-certificates && \
    curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/7fa2af80.pub | apt-key add - && \
    echo "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64 /" > /etc/apt/sources.list.d/cuda.list && \
    echo "deb https://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu2004/x86_64 /" > /etc/apt/sources.list.d/nvidia-ml.list

# The following cuda libraries are required to compile igibson
apt-get update && apt-get update && apt-get install -y --no-install-recommends \
    nvidia-headless-470 \
    cuda-cudart-11-1=11.1.74-1 \
    cuda-compat-11-1 \
    cuda-command-line-tools-11-1=11.1.1-1 \
    cuda-libraries-dev-11-1=11.1.1-1 \

# For building and running igibson
apt-get update && apt-get install -y --no-install-recommends \
    cmake \
    git \
    g++ \
    libegl-dev

Click to expand the code to install the dependencies including Nvidia drivers to render on screen for example on a desktop computer:

# Add the nvidia ubuntu repositories
apt-get update && apt-get install -y --no-install-recommends \
    gnupg2 curl ca-certificates && \
    curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/7fa2af80.pub | apt-key add - && \
    echo "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64 /" > /etc/apt/sources.list.d/cuda.list && \
    echo "deb https://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu2004/x86_64 /" > /etc/apt/sources.list.d/nvidia-ml.list

# The following cuda libraries are required to compile igibson
apt-get update && apt-get update && apt-get install -y --no-install-recommends \
    xserver-xorg-video-nvidia-470 \
    cuda-cudart-11-1=11.1.74-1 \
    cuda-compat-11-1 \
    cuda-command-line-tools-11-1=11.1.1-1 \
    cuda-libraries-dev-11-1=11.1.1-1 \

# For building and running igibson
apt-get update && apt-get install -y --no-install-recommends \
    cmake \
    git \
    g++ \
    libegl-dev

By default, iGibson builds with CUDA support which requires that nvcc is on your path (or CUDA 11 is symlinked to /usr/local/cuda from /usr/local/cuda-11.1). Cmake uses nvcc to find the CUDA libraries and headers when building iGibson. Add the following to your shell rc (.bashrc, .zshrc, etc.) and re-login to your shell (exec bash, exec zsh, etc.):

export PATH=/usr/local/cuda-11.1/bin:$PATH

Then verify nvcc is on your PATH:

$ nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2020 NVIDIA Corporation
Built on Mon_Oct_12_20:09:46_PDT_2020
Cuda compilation tools, release 11.1, V11.1.105
Build cuda_11.1.TC455_06.29190527_0

In case you want to build without CUDA support (used for the “rendering to GPU tensor” feature), you will have to set USE_CUDA to False in iGibson/igibson/render/CMakeLists.txt.

Installing iGibson

We provide 3 methods to install the simulator. After installing the simulator, you will need to download assets and datasets of scenes and object models.

1. pip

iGibson’s simulator can be installed as a python package using pip:

pip install igibson  # This step takes about 4 minutes
# run the demo
python -m igibson.examples.environments.env_nonint_example

2. Compile from source

Alternatively, iGibson can be compiled from source: iGibson GitHub Repo. First, you need to install anaconda following the guide on their website. Then:

git clone https://github.com/StanfordVL/iGibson --recursive
cd iGibson

# if you didn't create the conda environment before:
conda create -y -n igibson python=3.8
conda activate igibson

pip install -e . # This step takes about 4 minutes

We recommend the second method if you plan to modify iGibson in your project. If you plan to use it as it is to train navigation and manipulation agents, the pip installation or docker image should meet your requirements.

Note: If you are not using conda, you will need the system packages python3-dev (header files to build Python extensions) and python3-opencv (provides opencv and its dependencies).

3. Docker image

Docker provides an easy way to reproduce the development environment across platforms without manually installing the software dependencies. We have prepared docker images that contain everything you need to get started with iGibson.

First, install Docker from the official website. Please make sure that the docker version is at least v19.0 to enable native GPU support.

We provide two images:

igibson/igibson:latest: smaller image, but does not support GUI.
igibson/igibson-vnc:latest: supports GUI and remote desktop access via VNC.

We also provide scripts to build the images from scratch:

# image without GUI:
cd iGibson/docker/igibson
./build.sh

# image with GUI and VNC:
cd iGibson/docker/igibson-vnc
./build.sh

Issues

If you have installation issues, first, check our section for issues here. We have included solutions to previous known problems there.

If you couldn’t find a solution, search open and closed issues in our github issues page here.

If still no-luck, open a new issue in our github. Our turnaround is usually a couple of days.

The SVL pybullet fork

To optimize and accelerate physics simulation, we use a custom version of pybullet in iGibson. This is installed automatically if you install iGibson in a fresh conda environment, but if you already have a regular pybullet, you should manually remove it and install our fork as follows (otherwise your ‘pip install -e .’ will fail):

pip uninstall pybullet
pip install pybullet-svl

Downloading the Assets and Datasets of Scenes and Objects

Once the environment has been installed, we need to download the assets to enable the simulation including models of the robotic agents, objects, 3D scenes, etc. This process requires three simple steps.

First, we need to configure where the iGibson’s assets are going to be stored. The desired path should be indicated in your_installation_path/igibson/global_config.yaml. The default place to store the data is:

assets_path: your_installation_path/igibson/data/assets 
g_dataset_path: your_installation_path/igibson/data/g_dataset
ig_dataset_path: your_installation_path/igibson/data/ig_dataset
threedfront_dataset_path: your_installation_path/igibson/data/threedfront_dataset 
cubicasa_dataset_path: your_installation_path/igibson/data/assetscubicasa_dataset 

In case you prefer to store the assets in a different location, you can run the command:

python -m igibson.utils.assets_utils --change_data_path

Second, we need to download the robot models and some small objects from the assets bundle here and unpack it in the assets folder. More easily, this process can be automatically done by executing the command:

python -m igibson.utils.assets_utils --download_assets

Third, we need to download datasets of scenes (Gibson or iGibson), and, possibly, the BEHAVIOR Datasets of Object Models. For interactive tasks, you need to download iGibson Scenes and the BEHAVIOR Dataset of Objects. They include several fully interactive scenes and hundreds of 3D objects to use with our simulator. For navigation tasks, you could use the interactive scenes, but we also provide back-compatibility to the Gibson Dataset, Stanford 2D-3D-Semantics Dataset, and Matterport3D Dataset that include non-interactive scene models. Follow the detailed instructions here to download the aforementioned datasets.

Alternatively, to avoid downloading an entire dataset before you can test iGibson’s functionalities, we provide a single high quality small non-interactive scene (R’s) for demo and testing purposes. To download this demo data, run:

python -m igibson.utils.assets_utils --download_demo_data

Examples

We provide a lot of examples to get you started in your research! Check the folder igibson/examples and the description here.

After installing the code and downloading the demo data, you should be able to try out a simple robot navigation demo executing:

python -m igibson.examples.environments.env_nonint_example

Testing

To test iGibson installation, you can run

python
>> import igibson

For a full suite of tests and benchmarks, you can refer to tests for more details.

You can also run all tests by executing pytest within the iGibson installation folder. (For Mac users) Some tests will fail as they require a Nvidia GPU.

Uninstalling

Uninstalling iGibson is easy: pip uninstall igibson