build(macos): add Python venv support to setup script (#26702)

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>

.github/workflows/compile_macos.yml

@@ -44,7 +44,9 @@ jobs:
           macos-pip-${{ runner.arch }}-
 
     - name: setup
-      run: ./Tools/setup/macos.sh
+      run: |
+        ./Tools/setup/macos.sh
+        echo "${{ github.workspace }}/.venv/bin" >> $GITHUB_PATH
 
     - uses: ./.github/actions/setup-ccache
       id: ccache

Tools/setup/macos.sh

@@ -80,9 +80,20 @@ brew link --overwrite --force arm-gcc-bin@13
 
 # Python dependencies
 echo "[macos.sh] Installing Python3 dependencies"
+
+# Resolve to git repo root based on script location (handles submodules and subdirectory invocation)
+ROOT_DIR="$(git -C "$DIR" rev-parse --show-toplevel 2>/dev/null || echo "$DIR")"
+VENV_DIR="$ROOT_DIR/.venv"
+
+# Create virtual environment if it doesn't exist
+if [ ! -d "$VENV_DIR" ]; then
+	echo "[macos.sh] Creating Python virtual environment at $VENV_DIR"
+	python3 -m venv "$VENV_DIR"
+fi
+
 # We need to have future to install pymavlink later.
-python3 -m pip install future
+"$VENV_DIR/bin/pip" install future
-python3 -m pip install --user -r ${DIR}/requirements.txt
+"$VENV_DIR/bin/pip" install -r "${DIR}/requirements.txt"
 
 # Optional, but recommended additional simulation tools:
 if [[ $INSTALL_SIM == "--sim-tools" ]]; then
@@ -100,4 +111,12 @@ if [[ $INSTALL_SIM == "--sim-tools" ]]; then
 	fi
 fi
 
+echo ""
 echo "[macos.sh] All set! The PX4 Autopilot toolchain was installed."
+echo ""
+echo "Python dependencies were installed into a virtual environment at:"
+echo "    $VENV_DIR"
+echo ""
+echo "Activate it before building (run in each new terminal session):"
+echo "    source $VENV_DIR/bin/activate"
+echo ""

docs/en/dev_setup/dev_env_mac.md

@@ -8,7 +8,7 @@ This environment can be used to build PX4 for:
 
 It works on both Intel and Apple Silicon Macs.
 
-:::tip
+::: tip
 This setup is supported by the PX4 dev team.
 To build for [other targets](../dev_setup/dev_env.md#supported-targets) you will need to use a [different OS](../dev_setup/dev_env.md#supported-targets) or an [unsupported development environment](../advanced/community_supported_dev_env.md).
 :::
@@ -38,7 +38,7 @@ To build for [other targets](../dev_setup/dev_env.md#supported-targets) you will
 
 4. **Ensure Python 3 is available.** Some PX4 build scripts require `python3` and `pip3` to be in your `PATH`. The Xcode Command Line Tools include Python 3 by default.
 
-   :::tip
+   ::: tip
    If you need to install or manage a different Python version, we recommend [pyenv](https://github.com/pyenv/pyenv), which lets you set global and per-directory Python versions.
    :::
 
@@ -58,6 +58,18 @@ To build for [other targets](../dev_setup/dev_env.md#supported-targets) you will
    ./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:
+
+   ```sh
+   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](https://direnv.net/) or add the activation to your `~/.zshrc`.
+   :::
+
    This installs:
    - **Toolchain packages** from the `osx-cross/arm` and `PX4/px4` Homebrew taps — ARM cross-compiler (`arm-gcc-bin@13`), `cmake`, `ninja`, `ccache`, `fastdds`, `genromfs`, `kconfig-frontends`, and other build tools
    - **Python packages** from `requirements.txt`