ArduPilot / ArduPilot/MAVProxy

Docs: macOS installation instructions fail on modern macOS (PEP 668 / externally-managed-environment)

Open Beginner friendly
#1,657 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
595
Forks
773
Avg merge
2d 6h
Merged PRs (30d)
18

Description

**Issue details**
I was following the macOS installation guide today on my MacBook Air (Sonoma), and the `pip install` command failed with the `externally-managed-environment` error.

**Screenshot 1: The current documentation**

Image

**Version**
Latest macOS (Sonoma/Sequoia)

**Platform**
[X] Mac

**Description**
The current macOS documentation recommends using `python3 -m pip install ... --user` or `brew install python`. This fails on modern macOS versions because of **PEP 668** system protection, which prevents pip from modifying the system-managed Python environment.

**Steps to Reproduce**
1. On a fresh macOS installation (Sonoma 14.x or newer).
2. Run the command from the docs: `python3 -m pip install mavproxy pymavlink --user --upgrade`.

**Actual Behavior**
The installation is blocked by the OS with the following error:

**Screenshot 2: The terminal error**

Image

**Proposed Solution**
The documentation should be updated to explicitly recommend installing within a virtual environment (`venv`) or using `pipx`.

**Recommended update for the Mac section:**
```bash
# Create a virtual environment to avoid PEP 668 errors
python3 -m venv venv
source venv/bin/activate

# Install inside the virtual environment
pip install MAVProxy pymavlink

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the macOS installation guide's Mac section and find the documented `pip install` command using `--user`. Update the instructions to recommend a virtual environment or pipx, using the proposed venv commands as a guide. Done means a fresh modern macOS installation has a documented path that avoids the PEP 668 externally-managed-environment error.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.