# MacOS Development Environment

The following instructions set up a PX4 development environment for macOS. This environment can be used to build PX4 for:

Apple M1 Macbook users!

If you have an Apple M1 Macbook, make sure to run the terminal as x86 by setting up an x86 terminal:

  1. Locate the Terminal application within the Utilities folder (Finder > Go menu > Utilities)
  2. Select Terminal.app and right-click on it, then choose Duplicate.
  3. Rename the duplicated Terminal app, e.g. to x86 Terminal
  4. Now select the renamed x86 Terminal app and right-click and choose *Get Info
  5. Check the box for Open using Rosetta, then close the window
  6. Run the x86 Terminal as usual, which will fully support the current PX4 toolchain


This setup is supported by the PX4 dev team. To build other targets you will need to use a different OS (or an unsupported development environment).

# Video Guide

# Homebrew Installation

The installation of Homebrew is quick and easy: installation instructions (opens new window).

# Enable more open files (Handle "LD: too many open files" error)

Create the ~/.zshenv file or append it (by running open ~/.zshenv on the terminal) and add this line:

ulimit -S -n 2048

# Enforce Python Version

If not already existing, create the file ~/.zshrc and add these lines:

# Point pip3 to MacOS system python 3 pip
alias pip3=/usr/bin/pip3

# Common Tools

After installing Homebrew, run these commands in your shell to install the common tools:

brew tap PX4/px4
brew install px4-dev

Install the required Python packages

# install required packages using pip3
python3 -m pip install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema
# if this fails with a permissions error, your Python install is in a system path - use this command instead:
sudo -H python3 -m pip install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema

# Gazebo Simulation

First run the following commands:

brew unlink tbb
brew install tbb@2020
brew link tbb@2020


September 2021: The commands above are a workaround to this bug: PX4-Autopilot#17644 (opens new window). They can be removed once it is fixed (along with this note).

To install SITL simulation with Gazebo:

brew install --cask temurin
brew install --cask xquartz
brew install px4-sim-gazebo

Run this macOS setup script: PX4-Autopilot/Tools/setup/macos.sh The easiest way to do this is to clone the PX4 source, and then run the script from the directory, as shown:

git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot/Tools/setup
sh macos.sh

# jMAVSim Simulation

To use SITL simulation with jMAVSim you need to install a recent version of Java (e.g. Java 15). You can download Java 15 (or later) from Oracle (opens new window) or use Eclipse Temurin (opens new window):

brew install --cask temurin

Then install jMAVSim:

brew install px4-sim-jmavsim


PX4 v1.11 and beyond require at least JDK 15 for jMAVSim simulation.

For earlier versions, macOS users might see the error Exception in thread "main" java.lang.UnsupportedClassVersionError:. You can find the fix in the jMAVSim with SITL > Troubleshooting).

# Next Steps

Once you have finished setting up the command-line toolchain: