The Honest Guide to Setting Up a Linux Based Robotics Development Environment From Scratch

Let’s be real: setting up a robotics development environment is rarely fun. It's a tangled mess of toolchains, kernel modules, and dependency hell. But if you're reading this, you've decided to take the plunge—and I’m here to make sure you don't drown in the deep end.

This isn't a step-by-step tutorial where we pretend everything works perfectly on the first try. This is the honest, battle-tested path to getting a Linux system ready for real robotics work, from bare metal to running your first simulation.

Why Linux? Because Windows Will Fight You

If you’re building a robot, you’re not just running Python scripts. You’re dealing with real-time control, hardware interfaces (GPIO, CAN bus, serial ports), and sensor drivers that were written by people who assume you’re running Ubuntu. Windows can do some of this—via WSL2 or Docker—but the moment you need direct hardware access, you're in a world of pain.

Linux gives you /dev access, modprobe, and a kernel that doesn’t hide behind layers of abstraction. Stick with Ubuntu 22.04 LTS or 24.04 LTS for the best balance of package availability and ROS2 support.

Step 1: The OS Install – Don’t Overthink It

I know, I know—everyone has a favorite distro. But for robotics, Ubuntu is the standard. The ROS2 documentation, the hardware vendors, the forums—they all assume Ubuntu. Save yourself headaches.

• Ubuntu 22.04 LTS: Best for ROS2 Humble or Foxy. Solid, well-tested.
• Ubuntu 24.04 LTS: Bleeding edge, but some packages (like older Gazebo versions) may lag. Only if you need newer kernels.

Pro tip: Install with minimal software selection. You don’t need all the office suite and games. Use ubuntu-server image if you’re comfortable with CLI—then add desktop later with sudo apt install ubuntu-desktop.

Step 2: Essential Tools – The Core Arsenal

After booting into your fresh system, run this to get the basics that every robotics developer actually uses daily:

sudo apt update && sudo apt upgrade -y
sudo apt install git curl wget vim build-essential cmake python3-pip python3-venv net-tools usbutils

Don’t skip usbutils – it gives you lsusb, which is your best friend when plugging in an Arduino or lidar and wondering if it’s even detected.

Step 3: ROS2 – The Heart of Modern Robotics

Skip ROS1 unless you're maintaining legacy hardware. ROS2 is where the community is now.

Install ROS2 Humble (Ubuntu 22.04)

Follow the official install instructions, but here’s the honest version:

sudo apt install software-properties-common
sudo add-apt-repository universe
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update
sudo apt install ros-humble-desktop

This installs everything: the core, the build tools, RViz, and Gazebo. It’s about 2GB—worth it.

You will also need:

sudo apt install python3-colcon-common-extensions ros-humble-xacro
sudo pip3 install -U colcon-common-extensions

And always source your workspace:

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

Step 4: Gazebo (Ignition) – Not ROS1 Gazebo

The “old” Gazebo (Classic) is deprecated. Use Ignition Gazebo (now called just Gazebo). For ROS2 Humble, install ros-humble-ros-gz-sim.

But here’s the honest truth: Gazebo simulations are flaky out of the box. Expect to spend time tuning model files and SDFormat parameters. Have this ready:

sudo apt install ros-humble-gazebo-ros-pkgs

Actually no—that’s the old one. For the new Gazebo:

sudo apt install ros-humble-ros-gz-sim

Yes, the naming is a mess. That’s just how it is.

Step 5: Python Environment – Use Venv, Don’t Rely on System Python

Robotics means you'll end up installing numpy, opencv-python, scipy, transforms3d, and maybe some deep learning libraries. Never pip install globally—it will break apt packages.

Instead:

python3 -m venv ~/robotics_env
source ~/robotics_env/bin/activate
pip install numpy opencv-python-headless transforms3d matplotlib

Add that source line to your ROS2 launch scripts or a dedicated alias.

Step 6: Hardware Access – The Pain Point You Can’t Avoid

You will inevitably need to communicate with motors, sensors, or microcontrollers. This is where things break.

Serial ports

If you’re using an Arduino or any USB-serial device, add yourself to the dialout group:

sudo usermod -a -G dialout $USER
log out and back in

Otherwise, you get permission denied errors every time you open /dev/ttyUSB0.

GPIO on Raspberry Pi or Jetson

Don’t use the default Python RPi.GPIO library—it’s deprecated. Use gpiozero or libgpiod for modern kernel compatibility.

For NVIDIA Jetsons, you need sudo apt install nvidia-jetpack (if using L4T) and then the Jetson.GPIO library from GitHub.

Real-time kernel (optional, but game-changing)

If you're doing low-latency control loops, consider installing linux-image-rt-* or the PREEMPT_RT kernel. Ubuntu 22.04 has a real-time kernel option—install with:

sudo apt install linux-image-rt-amd64

Then reboot and select it from GRUB. Be warned: some graphics drivers may not work perfectly.

Step 7: Git Workflow – Because You Will Regret Not Having This

Set up Git properly from day one:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

Create a repos folder for all your robotics code, not scattered across the Desktop.

Step 8: Docker – When You Want Isolation Without Dual Boot

Sometimes you need a different ROS2 version or a specific simulation environment. Docker to the rescue.

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Then, for ROS2 containers, use the official osrf/ros images. This keeps your host system clean—but note that hardware access (USB, GPU) requires extra flags like --device and --runtime nvidia.

Common Pitfalls (That Nobody Warns You About)

• colcon build fails with cryptic Python errors – You probably have a package installed via pip that conflicts with the system Python. Use a virtualenv next time.
• RViz crashes on launch – Usually missing OpenGL or graphics drivers. Install mesa-utils and run glxinfo to check.
• cannot open shared object file – A package isn't installed or sourced. Double-check ROS_DISTRO and your setup.bash.
• Joystick not working in ROS2 – Install joy package and check ls /dev/input/js* permissions.

The 80/20 Rule for Your First Week

Don’t try to build a full autonomous robot on day one. Instead, aim for this by the end of your first week:

1. ROS2 talker/listener example working
2. Launch Gazebo with a simple differential drive robot model
3. RViz displaying laser scan data
4. Serial communication with an Arduino (even just blinking an LED)

Once that works, you have a solid foundation. Then you can start adding SLAM, navigation, or computer vision—without wanting to throw your laptop out the window.

Final Honest Advice

• Backup your configuration files (~/.bashrc, ~/.profile, colcon workspace) to a private Git repo. You will reinstall your OS at least twice.
• Document everything you install because in six months you won’t remember why you built a custom kernel module.
• Join the ROS Discourse and the relevant community forum for your hardware (like Team BlackSheep or JetsonHacks). The official docs are good, but real-world answers come from forums.

Setting up a robotics development environment is a rite of passage. It’s frustrating, but every error you fix teaches you something valuable about how your system works. Once it’s running, you’ll have a machine that can control a physical robot in real-time—and that feeling is worth every headache.