ArduPilot / ArduPilot/MAVProxy
Docs: macOS installation instructions fail on modern macOS (PEP 668 / externally-managed-environment)
- 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**
**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**
**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