Installation

This guide will help you install OmniEmbodied on your system.

Requirements

System Requirements

Operating System: Linux (Ubuntu 18.04+), macOS (10.14+), or Windows 10+
Python: 3.8 or higher
Memory: At least 8GB RAM recommended
Storage: At least 5GB free disk space

Python Dependencies

The main dependencies are automatically installed with OmniEmbodied:

numpy >= 1.19.0
pandas >= 1.3.0
pyyaml >= 5.4.0
tqdm >= 4.62.0
pathlib >= 1.0.1

Optional Dependencies

For enhanced functionality, you may want to install:

openai >= 0.27.0 - For OpenAI API integration
anthropic >= 0.3.0 - For Anthropic Claude integration
torch >= 1.9.0 - For neural network components
matplotlib >= 3.3.0 - For visualization
jupyter >= 1.0.0 - For notebook examples

Installation Methods

Install from Source (Recommended)

Clone the repository and install:

git clone https://github.com/ZJU-REAL/OmniEmbodied.git
cd OmniEmbodied/OmniSimulator
pip install -e .
cd ..
pip install -r requirements.txt

Create a virtual environment (optional but recommended):

# Using conda
conda create -n omniembodied python=3.8
conda activate omniembodied

# Or using virtualenv
python -m venv omniembodied-env
source omniembodied-env/bin/activate  # On Windows: omniembodied-env\Scripts\activate

Configuration

After installation, configure your LLM API key in config/baseline/llm_config.yaml:

api:
  provider: "deepseekv3"  # Choose your provider: deepseekv3, gpt-4, etc.
  providers:
    deepseekv3:
      api_key: "your-api-key-here"  # Replace with your actual API key
      model: "deepseek-chat"
      temperature: 0.3
      max_tokens: 2048

For Global Observation Mode

If you plan to run scripts ending with -wg.sh (with global observation), you need to configure:

Set runtime parameter: Use --observation-mode global when running

Configure simulator: Set global_observation: true in config/simulator/simulator_config.yaml

# config/simulator/simulator_config.yaml
global_observation: true  # Enable global observation mode

Verification

To verify your installation, run the following command:

python -c "import OmniSimulator; print('OmniEmbodied installed successfully!')"

You can also run the test suite:

python -m pytest tests/

Running Your First Evaluation

Run a basic evaluation with:

bash scripts/deepseekv3-wo.sh

Troubleshooting

Common Issues

Import Error: No module named ‘OmniSimulator’

This usually means the OmniSimulator subpackage wasn’t installed correctly. Try:

cd OmniSimulator
pip install -e .

Permission denied errors on Windows

Run your terminal as administrator, or use:

pip install --user -e .

YAML parsing errors

Make sure you have the correct version of PyYAML:

pip install --upgrade PyYAML>=5.4.0

Memory issues during installation

If you encounter memory issues, try installing with fewer parallel jobs:

pip install -e . --no-cache-dir

Platform-Specific Notes

Linux

On Ubuntu/Debian, you might need to install additional system packages:

sudo apt-get update
sudo apt-get install python3-dev build-essential

macOS

Make sure you have Xcode command line tools installed:

xcode-select --install

Windows

We recommend using Anaconda or Miniconda on Windows for easier dependency management.

Getting Help

If you encounter issues during installation:

Check our Troubleshooting guide
Search existing GitHub Issues
Create a new issue with your system information and error messages

Next Steps

Once you have OmniEmbodied installed, check out the Quick Start guide to run your first simulation!