Installation

The ecosystem targets ROS Noetic on Ubuntu 20.04 with Python 3.8, Gazebo Classic 11, Gymnasium 0.29.1, and Stable Baselines 3 2.x.

Note

ROS Noetic and Gazebo Classic are end-of-life as of 2025. This framework is a research artifact targeting that pinned environment for reproducibility with the published paper. New production work should consider a ROS 2 / modern Gazebo migration — that’s out of scope for the current codebase but tracked as future work.

There are three install paths:

  • Option A — bootstrap script on a native Ubuntu 20.04 host. Fastest for users who can install Ubuntu 20.04 directly.

  • Option B — manual install on a native Ubuntu 20.04 host. Same end state as A; useful for users who want to step through each piece.

  • Option C — Docker image on any Linux host (Ubuntu 20.04 / 22.04 / 24.04, plus WSL2 on Windows). The right choice if your machine ships with Ubuntu 22.04+ or has a GPU / driver combo that has no Ubuntu 20.04 support — common on modern OEM laptops and on RTX 50-series workstations.

Option B — manual installation

1. ROS Noetic

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt install curl
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt update
sudo apt install ros-noetic-desktop-full

echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

sudo apt install python3-rosdep python3-rosinstall \
                 python3-rosinstall-generator python3-wstool \
                 build-essential
sudo rosdep init
rosdep update

2. Catkin tools + workspace

sudo apt-get install python3-catkin-tools

mkdir -p ~/uniros_ws/src
cd ~/uniros_ws/
catkin build
echo "source ~/uniros_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

3. System dependencies

The framework needs xterm (for log windows), MoveIt (motion planning), and PyKDL / kdl_parser_py / trac_ik (kinematics):

sudo apt install \
    xterm \
    ros-noetic-moveit \
    python3-pykdl \
    ros-noetic-kdl-parser-py \
    ros-noetic-trac-ik \
    ros-noetic-urdfdom-py

The Kinematics_pykdl helper relies on a Noetic-compatible fork of pykdl_utils and hrl_geom:

cd ~/uniros_ws/src
git clone https://github.com/ncbdrck/hrl-kdl.git

cd ~/uniros_ws/src/hrl-kdl/pykdl_utils
python3 setup.py build
sudo python3 setup.py install

cd ~/uniros_ws/src/hrl-kdl/hrl_geom
python3 setup.py build
sudo python3 setup.py install

4. Clone the framework

UniROS bundles MultiROS and RealROS as git submodules, so one recursive clone gives you all three packages:

cd ~/uniros_ws/src
git clone --recurse-submodules -b gymnasium https://github.com/ncbdrck/UniROS

# Make sure every submodule is on the gymnasium branch
cd ~/uniros_ws/src/UniROS
git checkout gymnasium
git submodule update --remote --recursive

If you already have MultiROS or RealROS cloned standalone, skip --recurse-submodules and use the existing clones; just be sure they’re on the gymnasium branch.

Workspace layouts

Two layouts are supported, both work:

A. Submodule layout (recommended for new users / RTD) — one recursive clone of UniROS pulls MultiROS and RealROS in as submodules under UniROS/multiros/ and UniROS/realros/.

B. Sibling layout (common for active developers) — clone MultiROS and RealROS as standalone packages alongside UniROS in the catkin src/ directory. This is what an active developer often ends up with: catkin can’t host two packages with the same <name>, so once you start editing MultiROS or RealROS directly it’s easier to have them as siblings of UniROS rather than as nested submodules.

The framework and the docs work the same in both layouts.

Clone sb3_ros_support and the two application packages (separate repos, not submodules):

cd ~/uniros_ws/src
git clone -b gymnasium https://github.com/ncbdrck/sb3_ros_support.git
git clone https://github.com/ncbdrck/rl_environments.git
git clone https://github.com/ncbdrck/rl_training_validation.git

5. Python dependencies

sudo apt-get install python3-pip

pip3 install -r ~/uniros_ws/src/UniROS/uniros/requirements.txt
pip3 install -r ~/uniros_ws/src/UniROS/multiros/requirements.txt
pip3 install -r ~/uniros_ws/src/UniROS/realros/requirements.txt
pip3 install -r ~/uniros_ws/src/sb3_ros_support/requirements.txt
pip3 install -r ~/uniros_ws/src/rl_environments/requirements.txt

6. Build the workspace

cd ~/uniros_ws
rosdep install --from-paths src --ignore-src -r -y
catkin build
source devel/setup.bash

7. Verify

python3 -c "import uniros, multiros, realros, sb3_ros_support, rl_environments; print('OK')"

Robot-specific extras

The pre-built envs need each robot’s vendor ROS packages plus the per-robot description-extras helper repo (table / cube / Kinect wrap; install_uniros_stack.sh clones all of them in one pass). Install the ones you’ll use:

Trossen ReactorX-200 + ViperX-300S (Interbotix arms)

cd ~/uniros_ws/src
git clone -b noetic https://github.com/Interbotix/interbotix_ros_core.git
git clone -b noetic https://github.com/Interbotix/interbotix_ros_manipulators.git
git clone -b noetic https://github.com/Interbotix/interbotix_ros_toolboxes.git

# Description-extras helpers (table / cube / Kinect wraps)
git clone https://github.com/ncbdrck/reactorx200_description.git
git clone https://github.com/ncbdrck/viperx300s_description.git
git clone https://github.com/ncbdrck/common-sensors.git

The Interbotix repos ship CATKIN_IGNORE markers in some subfolders the framework needs; install_uniros_stack.sh removes them automatically. If you cloned manually, see the script’s install_rl_environments step for the list of files to delete.

Niryo Ned 2

cd ~/uniros_ws/src
git clone https://github.com/NiryoRobotics/ned_ros.git
cd ned_ros
git submodule update --init ros-foxglove-bridge
pip install -r requirements.txt
sudo apt install sqlite3 ffmpeg build-essential -y

cd ~/uniros_ws/src
git clone https://github.com/ncbdrck/niryo_ned2_description_extras.git

Universal Robots UR5e + Robotiq 2F-85

sudo apt install ros-noetic-ur-robot-driver ros-noetic-ur-calibration

cd ~/uniros_ws/src
git clone -b noetic-devel https://github.com/ros-industrial/universal_robot.git
git clone https://github.com/filesmuggler/robotiq.git
git clone https://github.com/ncbdrck/ur5e_robotiq_85_moveit_config.git
git clone https://github.com/ncbdrck/ur5e_description_extras.git

ur5e_description_extras depends on all three of the above (ur_e_description from universal_robot, robotiq_description from the Robotiq fork, and ur5e_robotiq_85_moveit_config); none are in the Ubuntu / ROS apt mirror so they must be source-cloned.

The UR5e real launch wrapper (ur5e_real.launch) is still pending in ur5e_description_extras; sim is fully supported.

Real push / pick-and-place envs (any robot)

Push and PnP real envs subscribe to /cube_pose for the cube’s pose. The publisher lives in a separate helper repo:

cd ~/uniros_ws/src
git clone https://github.com/ncbdrck/rl_envs_cube_tracker.git

See rl_envs_cube_tracker/README.md for camera-driver setup (Kinect v2, ZED 2, and D405 are supported; D405 is the only one the bootstrap script installs) and for per-camera-per-robot extrinsic calibration instructions.

Then rebuild the workspace and source it again.

Option C — Docker

If your host can’t run Ubuntu 20.04 natively (modern OEM laptop, Ubuntu 22.04 / 24.04, a GPU + driver stack with no Ubuntu 20.04 support, or Windows with WSL2), the same stack ships as a Docker image in two variants:

git clone -b gymnasium https://github.com/ncbdrck/UniROS.git
cd UniROS/docker

# Default (CUDA-runtime base, ~16 GB)
./build.sh
./run_gui.sh

# — or — slim (no CUDA in image, ~12 GB; matches the TIAGo pattern)
./build.sh --slim
./run_gui.sh -t uniros:noetic-slim

# add --mujoco to either variant to bake in the experimental MuJoCo
# backend (mujoco_ros_pkgs + MuJoCo + the example vx300s_mujoco_envs);
# omit it for a Gazebo-only image (the default)
./build.sh --mujoco

Note

If you’re already running Ubuntu 20.04 natively, use Option A or B above on the host directly — skip Docker. The native path is faster, smaller, and avoids GL-passthrough / nvidia-container-toolkit compatibility quirks that have surfaced on 20.04 hosts with newer NVIDIA driver branches. Docker is for hosts that can’t install 20.04 natively.

See Docker for the full Docker reference — variant comparison, hardware passthrough (USB and network), GPU, bind-mounting a host workspace for active development, troubleshooting, and the roadmap for in-progress features.

Next step

Continue with Quickstart to launch your first env.