Files
PX4-Autopilot/docs/en/dev_setup/dev_env_mac.md
T
Ramon RocheandFarhang 51b9a86a7e docs(dev_setup): refresh macOS environment page to match macos.sh (#28295)
The macOS setup page has not been edited since 2026-04-20, while
Tools/setup/macos.sh changed five times after that. The page still
describes the px4-sim Homebrew formula, which has been a deprecated
no-op in PX4/homebrew-px4 since 2026-04-20, and tells users to add
simulation later with `brew install px4-sim`, which installs nothing.
On Homebrew 6.0+ it does not even load, because the page never mentions
the tap trust the script now performs.

Stop enumerating the script's packages and taps in the page; that list
is what went stale. Say what the script does in one sentence, point at
macos.sh as the source of truth, and document only the user-facing
behaviour: Gazebo, XQuartz and a JDK come with --sim-tools, that path
needs sudo, taps are trusted for Homebrew 6, and the way to add
simulation later is to re-run the script with --sim-tools. Drop the
Python prerequisite; the script installs Python and creates the venv
itself.

Fix the pages it links to that contradict it: the simulation overview
still marked Gazebo on Apple Silicon as unstable (pre-dates the
2026-04-20 fix), the supported-targets table claimed Gazebo Classic on
macOS with nothing installing it, the jMAVSim page said Java must be
installed manually on macOS, and the build troubleshooting page
recommended ulimit 300 and running mac_set_ulimit.sh as a script (which
cannot change the caller's shell limit).

Assisted-by: Claude:claude-fable-5

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Farhang <46557204+farhangnaderi@users.noreply.github.com>
2026-09-07 13:14:34 -04:00

4.9 KiB

macOS Development Environment

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

It works on both Intel and Apple Silicon Macs. PX4 CI exercises this setup on Apple Silicon runners only; Intel is not covered by CI.

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

Development Environment Setup

Prerequisites

  1. Install Xcode Command Line Tools, which provide git, make, and the Apple clang compiler:

    xcode-select --install
    
  2. Install Homebrew by following the installation instructions. The setup script below also installs Homebrew if it is missing.

  3. Increase the open-file limit. The PX4 build opens many files simultaneously and the macOS default limit (256) is too low. You may see "LD: too many open files" errors without this.

    Add the following line to your shell startup file so it applies to every new terminal session. macOS defaults to zsh since Catalina, so add it to ~/.zshrc (use ~/.bashrc if you use bash):

    echo "ulimit -S -n 2048" >> ~/.zshrc
    

    Then open a new terminal (or run source ~/.zshrc) for the change to take effect.

Install Development Tools

  1. Download PX4 Source Code:

    git clone https://github.com/PX4/PX4-Autopilot.git
    cd PX4-Autopilot
    git submodule update --init --recursive --force
    
  2. Install development environment libraries from the macos.sh helper script:

    ./Tools/setup/macos.sh --sim-tools
    

    ::: info The setup script creates a Python virtual environment at .venv in the repo root and installs all Python dependencies into it. This keeps PX4's Python requirements isolated from your system Python and avoids conflicts with Homebrew's externally-managed Python.

    Activate it before building:

    source .venv/bin/activate
    

    You'll need to re-run this command in each new terminal session. To activate it automatically when you cd into the repo, consider a tool like direnv or add the activation to your ~/.zshrc. :::

    The script installs the NuttX cross-compiler and build tools, the Python dependencies (into the .venv described above), and with --sim-tools the Gazebo simulation stack. It is the source of truth for what gets installed; read macos.sh for the details.

    ::: info Omit --sim-tools if you only need to build for NuttX hardware and don't need simulation. All Gazebo dependencies are optional at build time, so make px4_sitl still works without them.

    Use --reinstall to force reinstallation of the Homebrew formulas (useful if something is broken). :::

    ::: info The script installs from third-party Homebrew taps and marks them as trusted (brew trust) on Homebrew 6.0 and later, which refuses to load formulae from untrusted taps. With --sim-tools it will prompt for your password, since the XQuartz installer and the JDK link into /Library/Java/JavaVirtualMachines need sudo. :::

Gazebo Simulation

The --sim-tools flag installs Gazebo and the libraries PX4's simulation modules build against.

If you skipped --sim-tools during initial setup and want to add simulation later, re-run the setup script with the flag (it is safe to run repeatedly):

./Tools/setup/macos.sh --sim-tools

::: info The script also installs XQuartz. macOS may require you to log out and back in after XQuartz is first installed. :::

Verify Installation

After installation, verify the key tools are available:

# NuttX cross-compiler
arm-none-eabi-gcc --version

# Build tools
cmake --version
ninja --version

# Gazebo (if --sim-tools was used)
gz sim --versions

As a quick smoke test, build and run a simulation target:

make px4_sitl gz_x500

If everything is set up correctly, this will build PX4 SITL and launch a Gazebo simulation with the x500 quadcopter.

Next Steps

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

  • Install VSCode (if you prefer using an IDE to the command line).

  • Install the QGroundControl Daily Build

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