Install#

IR-SIM supports Python 3.10+ on Linux, macOS, and Windows. You can use pip or conda for installation.

Instructions

Install IR-SIM using pip:

python -m pip install ir-sim

This will install the package and core dependencies for the base environment.

conda is a system for package and environment management.

  1. Install conda.

2. Create a new conda environment with Python and pip,

conda create --name irsim_env python=3.12 pip
conda activate irsim_env

or activate an existing one

3. Install ir-sim in the virtual environment

python -m pip install ir-sim

uv is an extremely fast Python package and project manager.

Install IR-SIM using uv:

uv venv
uv pip install ir-sim

or use uv’s project management:

uv add ir-sim

We strongly recommend using a fresh virtual environment (uv or conda) when installing IR-SIM from source.

Perform the following steps to install IR-SIM from source:

  1. Clone the official IR-SIM git repository, or a newly minted fork of the IR-SIM repository.

git clone https://github.com/hanruihua/ir-sim.git

  1. Navigate to the top-level of the cloned directory.

cd ir-sim

  1. If you want to use IR-SIM with editable source code, run

python -m pip install -e .

otherwise, run

python -m pip install .

or for uv users, run

uv sync

Verify the Installation#

Using the Python interpreter from the environment where IR-SIM was installed, print the installed version:

python -c "import irsim; print(irsim.__version__)"

If this command prints a version without an import error, the core installation is ready. Continue with the Quick Start to run a scene.

Install with Additional Features#

Keyboard Control

IR-SIM supports keyboard control for interactive robot simulation. Install the keyboard control dependencies:

python -m pip install "ir-sim[keyboard]"

This installs:

  • pynput - For keyboard and mouse input handling

All Features

To install all optional runtime dependencies and features:

python -m pip install "ir-sim[all]"

This includes:

  • Keyboard control (pynput)

  • Enhanced video support (imageio[ffmpeg])

  • ORCA group behavior (pyrvo)

Developer Setup#

The following dependency groups are only needed when developing IR-SIM itself. They are not required to run normal simulations.

Linting

IR-SIM uses Ruff for linting. To install the dependency-groups for linting locally, run

uv sync --group lint

This includes:

  • Ruff - Linting tool

  • ty - Type hinting tool

  • black - Code formatter

Testing

Install test dependencies using the test group (from pyproject.toml):

uv sync --group test

Run the tests:

uv run pytest

Generate coverage:

uv run pytest --cov . --cov-report=xml --cov-report=html

Type-check the codebase:

uvx ty check
Documentation

Install documentation dependencies using the docs group (from pyproject.toml):

uv sync --group docs

Build the docs locally (HTML):

cd docs
make html

The output will be available under docs/build/html (or docs/_build/html depending on your environment setup).

All Development Groups

To install all development dependency groups:

uv sync --all-groups

This includes:

  • lint group

  • test group

  • docs group