Installation Guide

Installing Isaac Sim

Caution

We have dropped support for Isaac Sim versions 2023.1.0 and below. We recommend using the latest Isaac Sim 2023.1.1 release.

For more information, please refer to the Isaac Sim release notes.

Downloading pre-built binaries

Please follow the Isaac Sim documentation to install the latest Isaac Sim release.

To check the minimum system requirements,refer to the documentation here.

Note

We have tested Orbit with Isaac Sim 2023.1.1 release on Ubuntu 20.04LTS with NVIDIA driver 525.147.

Configuring the environment variables

Isaac Sim is shipped with its own Python interpreter which bundles in the extensions released with it. To simplify the setup, we recommend using the same Python interpreter. Alternately, it is possible to setup a virtual environment following the instructions here.

Please locate the Python executable in Isaac Sim by navigating to Isaac Sim root folder. In the remaining of the documentation, we will refer to its path as ISAACSIM_PYTHON_EXE.

Note

On Linux systems, by default, this should be the executable python.sh in the directory ${HOME}/.local/share/ov/pkg/isaac_sim-*, with * corresponding to the Isaac Sim version.

To avoid the overhead of finding and locating the Isaac Sim installation directory every time, we recommend exporting the following environment variables to your terminal for the remaining of the installation instructions:

# Isaac Sim root directory
export ISAACSIM_PATH="${HOME}/.local/share/ov/pkg/isaac_sim-2023.1.0-hotfix.1"
# Isaac Sim python executable
export ISAACSIM_PYTHON_EXE="${ISAACSIM_PATH}/python.sh"

For more information on common paths, please check the Isaac Sim documentation.

Running the simulator

Once Isaac Sim is installed successfully, make sure that the simulator runs on your system. For this, we encourage the user to try some of the introductory tutorials on their website.

For completeness, we specify the commands here to check that everything is configured correctly. On a new terminal (Ctrl+Alt+T), run the following:

• Check that the simulator runs as expected:

  # note: you can pass the argument "--help" to see all arguments possible.
  ${ISAACSIM_PATH}/isaac-sim.sh
  

• Check that the simulator runs from a standalone python script:

  # checks that python path is set correctly
  ${ISAACSIM_PYTHON_EXE} -c "print('Isaac Sim configuration is now complete.')"
  # checks that Isaac Sim can be launched from python
  ${ISAACSIM_PYTHON_EXE} ${ISAACSIM_PATH}/standalone_examples/api/omni.isaac.core/add_cubes.py
  

Attention

If you have been using a previous version of Isaac Sim, you need to run the following command for the first time after installation to remove all the old user data and cached variables:

${ISAACSIM_PATH}/isaac-sim.sh --reset-user

If the simulator does not run or crashes while following the above instructions, it means that something is incorrectly configured. To debug and troubleshoot, please check Isaac Sim documentation and the forums.

Installing Orbit

Organizing the workspace

Note

We recommend making a fork of the orbit repository to contribute to the project. This is not mandatory to use the framework. If you make a fork, please replace NVIDIA-Omniverse with your username in the following instructions.

If you are not familiar with git, we recommend following the git tutorial.

• Clone the orbit repository into your workspace:

  # Option 1: With SSH
  git clone git@github.com:NVIDIA-Omniverse/orbit.git
  # Option 2: With HTTPS
  git clone https://github.com/NVIDIA-Omniverse/orbit.git
  

• Set up a symbolic link between the installed Isaac Sim root folder and _isaac_sim in the orbit` directory. This makes it convenient to index the python modules and look for extensions shipped with Isaac Sim.

  # enter the cloned repository
  cd orbit
  # create a symbolic link
  ln -s ${ISAACSIM_PATH} _isaac_sim
  

We provide a helper executable orbit.sh that provides utilities to manage extensions:

./orbit.sh --help

usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-c] -- Utility to manage Orbit.

optional arguments:
   -h, --help           Display the help content.
   -i, --install        Install the extensions inside Orbit.
   -e, --extra [LIB]    Install learning frameworks (rl_games, rsl_rl, sb3) as extra dependencies. Default is 'all'.
   -f, --format         Run pre-commit to format the code and check lints.
   -p, --python         Run the python executable provided by Isaac Sim or virtual environment (if active).
   -s, --sim            Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
   -t, --test           Run all python unittest tests.
   -o, --docker         Run the docker container helper script (docker/container.sh).
   -v, --vscode         Generate the VSCode settings file from template.
   -d, --docs           Build the documentation from source using sphinx.
   -c, --conda [NAME]   Create the conda environment for Orbit. Default name is 'orbit'.

Setting up the environment

Attention

This step is optional. If you are using the bundled python with Isaac Sim, you can skip this step.

The executable orbit.sh automatically fetches the python bundled with Isaac Sim, using ./orbit.sh -p command (unless inside a virtual environment). This executable behaves like a python executable, and can be used to run any python script or module with the simulator. For more information, please refer to the documentation.

Although using a virtual environment is optional, we recommend using conda. To install conda, please follow the instructions here. In case you want to use conda to create a virtual environment, you can use the following command:

# Option 1: Default name for conda environment is 'orbit'
./orbit.sh --conda  # or "./orbit.sh -c"
# Option 2: Custom name for conda environment
./orbit.sh --conda my_env  # or "./orbit.sh -c my_env"

If you are using conda to create a virtual environment, make sure to activate the environment before running any scripts. For example:

conda activate orbit  # or "conda activate my_env"

Once you are in the virtual environment, you do not need to use ./orbit.sh -p to run python scripts. You can use the default python executable in your environment by running python or python3. However, for the rest of the documentation, we will assume that you are using ./orbit.sh -p to run python scripts. This command is equivalent to running python or python3 in your virtual environment.

Building extensions

To build all the extensions, run the following commands:

• Install dependencies using apt (on Ubuntu):

  sudo apt install cmake build-essential
  

• Run the install command that iterates over all the extensions in source/extensions directory and installs them using pip (with --editable flag):

  ./orbit.sh --install  # or "./orbit.sh -i"
  

• For installing all other dependencies (such as learning frameworks), execute:

  # Option 1: Install all dependencies
  ./orbit.sh --extra  # or "./orbit.sh -e"
  # Option 2: Install only a subset of dependencies
  # note: valid options are 'rl_games', 'rsl_rl', 'sb3', 'robomimic', 'all'
  ./orbit.sh --extra rsl_rl  # or "./orbit.sh -e rsl_r"
  

Verifying the installation

To verify that the installation was successful, run the following command from the top of the repository:

# Option 1: Using the orbit.sh executable
# note: this works for both the bundled python and the virtual environment
./orbit.sh -p source/standalone/tutorials/00_sim/create_empty.py

# Option 2: Using python in your virtual environment
python source/standalone/tutorials/00_sim/create_empty.py

The above command should launch the simulator and display a window with a black ground plane. You can exit the script by pressing Ctrl+C on your terminal or by pressing the STOP button on the simulator window.

If you see this, then the installation was successful! 🎉