# MacOS Setup

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

* Pixhawk and other NuttX-based hardware
* [jMAVSim Simulation](../../simulation/jmavsim)
* [Gazebo Classic Simulation](../../simulation/sim_gazebo_classic)

:::tip This setup is supported by the PX4 dev team. To build other targets you will need to use a [different OS](..#supported-targets) (or an [unsupported development environment](../../advanced/dev_env_unsupported)). :::

## Video Guide

@[youtube](https://youtu.be/tMbMGiMs1cQ)

## Base Setup

The "base" macOS setup installs the tools needed for building firmware, and includes the common tools that will be needed for installing/using the simulators.

### Environment Setup

:::details 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 :::

First set up the environment

1.  Enable more open files by appending the following line to the `~/.zshenv` file (creating it if necessary):

    ```sh
    echo ulimit -S -n 2048 >> ~/.zshenv
    ```

    :::note If you don't do this, the build toolchain may report the error: `"LD: too many open files"` :::
2.  Enforce Python 3 by appending the following lines to `~/.zshenv`

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

### Common Tools

To setup the environment to be able to build for Pixhawk/NuttX hardware (and install the common tools for using simulators):

1. Install Homebrew by following these [installation instructions](https://brew.sh).
2.  Run these commands in your shell to install the common tools:

    ```sh
    brew tap PX4/px4
    brew install px4-dev
    ```
3.  Install the required Python packages:

    ```sh
    # 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 Classic Simulation

To setup the environment for [Gazebo Classic](../../simulation/sim_gazebo_classic) simulation:

1.  Run the following commands in your shell:

    ```sh
    brew unlink tbb
    sed -i.bak '/disable! date:/s/^/  /; /disable! date:/s/./#/3' $(brew --prefix)/Library/Taps/homebrew/homebrew-core/Formula/tbb@2020.rb
    brew install tbb@2020
    brew link tbb@2020
    ```

    :::note September 2021: The commands above are a workaround to this bug: [PX4-Autopilot#17644](https://github.com/PX4/PX4-Autopilot/issues/17644). They can be removed once it is fixed (along with this note). :::
2.  To install SITL simulation with Gazebo Classic:

    ```sh
    brew install --cask temurin
    brew install --cask xquartz
    brew install px4-sim-gazebo
    ```
3.  Run the 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:

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

## jMAVSim Simulation

To setup the environment for [jMAVSim](../../simulation/jmavsim) simulation:

1.  Install a recent version of Java (e.g. Java 15). You can download [Java 15 (or later) from Oracle](https://www.oracle.com/java/technologies/javase-downloads.html) or use [Eclipse Temurin](https://adoptium.net):

    ```sh
    brew install --cask temurin
    ```
2.  Install jMAVSim:

    ```sh
    brew install px4-sim-jmavsim
    ```

    :::warning 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](../../../simulation/jmavsim#troubleshooting)). :::

## Next Steps

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

* Install [VSCode](vscode) (if you prefer using an IDE to the command line).
*   Install the [QGroundControl Daily Build](https://docs.qgroundcontrol.com/master/en/releases/daily_builds.html)

    :::tip The _daily build_ includes development tools that are hidden in release builds. It may also provide access to new PX4 features that are not yet supported in release builds. :::
* Continue to the [build instructions](../building_px4).
