PX4 Podman Sim Container

This workspace provisions a persistent Podman-based PX4 development and simulation container.

What it does

• Uses workspace/PX4-Autopilot as the persistent host workspace root mounted at /workspace/PX4-Autopilot in the container.
• Clones PX4 into workspace/PX4-Autopilot/px4_src, so your code changes survive container rebuilds.
• Builds a local Ubuntu 24.04 image with the official PX4 Ubuntu setup script, ROS 2 Jazzy, colcon / vcs / rosdep, Gazebo bridge packages, MAVROS, and common C++ / ROS tooling.
• Persists ccache, Gazebo state, pip cache, and shell history under state/.
• Uses a repo-local Podman btrfs graphroot under state/podman-storage, so it does not depend on the host's default Podman storage driver.
• Passes through X11 or Wayland plus /dev/dri when available, so Gazebo GUI can run from the container.

Version default

The default configuration is pinned to PX4 v1.16.1, which is the latest stable release as of 2026-04-20.

If you want to switch versions, copy .env.example to .env and edit:

cp .env.example .env

Then set:

PX4_REF=v1.16.1
PX4_IMAGE_OS=ubuntu:24.04
PX4_LOCAL_IMAGE=localhost/px4-sim-dev:v1.16.1
PX4_ROS_DISTRO=jazzy
PX4_GFX_BACKEND=auto

Usage

cp .env.example .env
chmod +x scripts/*.sh
./scripts/up.sh
./scripts/shell.sh

Directly launch the default Gazebo simulation:

./scripts/sitl.sh

Or choose a different Gazebo target:

./scripts/sitl.sh gz_x500_depth

The gz_x500_realsense target now launches the full RealSense stack inside the container: PX4 SITL in the craic world, MicroXRCEAgent, ros_gz_bridge parameter_bridge, and rviz2.

This target also publishes a downward RGB camera on /downward_camera/image_raw with camera info on /downward_camera/camera_info.

Stop the container without deleting your source tree or caches:

./scripts/down.sh

Start the existing container again without recreating it:

./scripts/up.sh

Force up.sh to recreate the container from the current image:

PX4_UP_FORCE_RECREATE=1 ./scripts/up.sh

Persistent paths

• workspace/PX4-Autopilot: persistent workspace root shared with the container
• workspace/PX4-Autopilot/px4_src: PX4 source tree and all build outputs
• state/ccache: compiler cache
• state/gz: Gazebo runtime and model cache
• state/pip-cache: Python package cache
• state/bash_history: interactive shell history
• state/podman-storage: project-local image and container storage used by Podman

Notes

• scripts/build-image.sh builds from Ubuntu 24.04, runs Tools/setup/ubuntu.sh, and layers ROS 2 Jazzy plus common ROS / vision dependencies on top.
• :Z is included on bind mounts for Podman SELinux compatibility.
• scripts/init-px4.sh refuses to switch branches or tags if the PX4 repo has uncommitted changes.
• The container uses host networking so QGroundControl or other local tooling can talk to PX4 SITL without extra port mapping.
• If your desktop blocks X11 access, run xhost +si:localuser:$USER on the host before ./scripts/up.sh.
• PX4_GFX_BACKEND=auto now prefers X11 / GLX when both X11 and Wayland are available, because Gazebo GUI is more stable that way in NVIDIA-backed containers. Set PX4_GFX_BACKEND=wayland if you explicitly want the native Wayland path.