externally-managed-environment on Mac: Which python3 Fails

I went looking for error: externally-managed-environment on the Mac mini that runs this blog, expecting to reproduce it in one command. It took three tries, because on this machine the command python3 -m pip install means three different things depending on which python3 answers. Two of the three never print that error at all. One of them installs the package anyway, into a directory that is not on PATH, and exits 0.

Then I broke Homebrew while probing. A throwaway test meant to plant a marker file inside a virtualenv deleted Homebrew's real one instead, because a venv's sysconfig stdlib path points at the base interpreter. I restored it from a byte-identical copy and verified the checksum, and that accident turned out to be the clearest explanation of why venvs are exempt. Details below.

Five interpreters, three pip policies

The machine is a Mac mini (Mac16,10, M4) on macOS 26.4.1 (25E253). Here is every Python on it as of 2026-09-25, with the marker file PEP 668 actually looks for: EXTERNALLY-MANAGED in the directory that sysconfig.get_path("stdlib", "posix_prefix") returns.

Interpreter	Version	Marker	pip	pip install cowsay
/usr/bin/python3 (Xcode CLT)	3.9.6	absent	21.2.4	exit 0, lands in ~/Library/Python/3.9
[email protected] (brew)	3.12.13_2	present, 1,053 B	26.1	blocked
[email protected] (brew)	3.13.15	present, 1,053 B	26.2	blocked
/opt/homebrew/bin/python3 (= 3.14)	3.14.7	present, 1,053 B	26.2.1	exit 1, the error
/tmp/imgenv/bin/python (venv)	3.14.7	base marker present	26.1.1	exit 0

The marker text is not written by Python or by pip. It is written by the Homebrew formula: homebrew-core's [email protected] has the line (lib_cellar/"EXTERNALLY-MANAGED").write <<~INI followed by the exact paragraphs you see in your terminal, which is why all three versions ship the same 1,053 bytes. PEP 668 only specifies the file name, the location, and that it is INI parsed by configparser; the wording is the distributor's.

Why Apple's python3 can never print it

Two independent reasons. First, there is no marker in the CLT framework's stdlib. Second, its pip is 21.2.4, and per pip's changelog the PEP 668 check arrived in 23.0 (2023-01-30) and --break-system-packages in 23.0.1 (2023-02-17). Apple's pip predates both. It does not even have --dry-run, which is how my first probe failed:

$ /usr/bin/python3 -m pip install --dry-run cowsay
no such option: --dry-run          # exit 2

Run it for real and it succeeds, quietly, somewhere else:

$ /usr/bin/python3 -m pip install -v cowsay
Defaulting to user installation because normal site-packages is not writeable
...
  WARNING: The script cowsay is installed in '/Users/sg-mini/Library/Python/3.9/bin'
  which is not on PATH.
Successfully installed cowsay-6.1   # exit 0

That fallback is not magic. It is in the pip that Apple ships, in pip/_internal/commands/install.py, function decide_user_install(): if site_packages_writable() is true it does a normal install, otherwise it returns true for a user install. The CLT site-packages directory is drwxr-xr-x root wheel, so on any normal account the answer is always the user directory. This is the "pip said Successfully installed but the command is not found" class of report, and on macOS it comes from the same root as the PEP 668 error: which interpreter you got.

What the gate actually covers

I ran each command against Homebrew's 3.14 and recorded the real exit code, with no pipe on the end. That last part matters: a | head reports the exit code of head, which is how I first convinced myself the blocked install had succeeded. I have written about that exact trap before and still walked into it.

Command (Homebrew python 3.14.7, pip 26.2.1)	Exit
pip install --dry-run cowsay	1, error
pip install --user --dry-run cowsay	1, error
pip uninstall -y cowsay	1, error
pip list / pip download cowsay -d /tmp/dl	0
pip install --break-system-packages --dry-run cowsay	0
PIP_BREAK_SYSTEM_PACKAGES=1 pip install --dry-run cowsay	0
uv pip install --python /opt/homebrew/bin/python3 cowsay	2, error
uv pip install ... --break-system-packages --dry-run	0

Two results are worth pulling out. --user on its own does not get you past the gate, even though Homebrew's error text recommends --user alongside the override. And uninstall is blocked too, with the gate firing before pip checks whether the package is installed at all.

The venv exemption is structural

I assumed a venv works because the marker is not inside it. Wrong. Inside /tmp/imgenv, sysconfig.get_path("stdlib", "posix_prefix") returns the base interpreter's stdlib, marker and all. pip installs anyway, because the check is skipped when sys.prefix != sys.base_prefix.

My probe did not discover that gracefully. It copied the marker "into the venv" and then deleted it; both paths resolved to Homebrew's Cellar, so cp replied that source and destination were identical and the rm took out the real file. I restored it from [email protected]'s copy, confirmed md5 c91d0893b714d7daac53d8a21ca21bbd, and confirmed the gate fires again with exit 1. The restored file now carries 3.13's timestamp instead of its own, which is the residue I am leaving in place rather than faking.

What this Mac ended up doing instead

The interesting part is not the error, it is what a year of working around it leaves behind. This machine has two separate escape hatches in use at once.

~/Library/Python/3.14/lib/python/site-packages holds 51 entries and 173 MB, with mtimes of 2026-07-21 (google-api-python-client 2.198.0, google-analytics-data 0.23.0, cryptography 49.0.0, grpcio 1.82.1) and 2026-07-31 (pyyaml 6.0.3). It is live: ENABLE_USER_SITE is true for brew 3.14, so import googleapiclient resolves there. A repo-wide grep for those imports in *.py returns zero files, so all 173 MB is an orphan from analytics work that has since been blocked at the credential layer. There is no pip.conf anywhere on the machine and no PIP_BREAK_SYSTEM_PACKAGES in any shell rc, which means the override was typed at a prompt months ago and nothing in the repo records the command.

Pillow, meanwhile, lives only in a venv at /tmp/imgenv, created 2026-09-22 12:34. Six scripts import PIL, including the one that draws every thumbnail on this blog. Putting a venv in /tmp on macOS was its own mistake, which I have already paid for more than once, and the current copy is a rebuild.

Homebrew's two sources also disagree about the hatch. The formula's error text tells you to pass --break-system-packages and adds --user; the documentation page says Do not use pip install --upgrade pip against Homebrew's externally managed base environment and never mentions the flag, recommending venv or pipx instead. That page also moved: the old /Homebrew-and-Python URL now redirects to Language-Runtimes-and-Packages, which is the kind of quiet move that breaks citations in old answers.

Nobody installed the Python that throws the error

brew uses --installed [email protected] lists gcloud-cli, mlx, mlx-c, ollama, and pipx. Nothing on this machine ever asked for Python 3.14 directly; it arrived under other formulas. Meanwhile [email protected] and [email protected] have zero installed dependents and sit in brew leaves, and the Cellar still holds two 3.14 builds (3.14.7 and 3.14.5). So the interpreter that refuses your pip install is usually a dependency you did not choose, at a version you did not pick.

The scheduler gets a different python than my shell

This is the part that changed how I write cron work here. launchctl getenv PATH is empty, so launchd jobs inherit the system default /usr/bin:/bin:/usr/sbin:/sbin. All seven com.mmm.* LaunchAgents on this machine have no EnvironmentVariables:PATH key, and the shell scripts they run call bare python3:

$ env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin python3 -V
Python 3.9.6
$ python3 -V            # my interactive SSH shell
Python 3.14.7

Checking that against the runners turned up a split I did not know about. Three scheduler scripts call python3; daily-revenue.sh and weekly-review.sh each export PATH with /opt/homebrew/bin prepended, so they get 3.14.7, while daily-report.sh sets no PATH at all and therefore runs our tracker code under Apple's 3.9.6 every night. Nothing is broken today: all 14 ops/**/*.py files compile under both interpreters (py_compile, 14 of 14, zero failures) because the scheduled ones use only the standard library. But the two interpreters have opposite pip policies, so an install step added to daily-report.sh would take the silent user-site path while the identical line in weekly-review.sh would fail with the error. Pin the interpreter by absolute path if it matters, which is the same lesson as what a launchd job actually inherits.

The advice you find is written for Debian

I checked where this error is discussed, because the answers I kept landing on did not match what I measured. Stack Exchange API, title=externally-managed-environment, page size 100: 14 questions on Stack Overflow, 1 on Super User, 1 on Ask Ubuntu, and zero on Apple Stack Exchange. The canonical question, at 1,057 votes and 38 answers, is tagged python, pip, debian, failed-installation. Of the 14 Stack Overflow titles, 4 name a Linux distribution and none mention macOS or Homebrew. On Hacker News, Algolia returns 5 stories for the error string and 8 for "PEP 668", topping out at 10 points on the 2023 Debian adoption thread.

So the macOS trigger, a Homebrew formula writing a file into its Cellar, is nearly absent from the record, and the top-voted advice is shaped by apt. On this machine the useful version is short. Use a venv, but not in /tmp. Use pipx for command-line tools, since it is already here as a 3.14 dependency. If you reach for --break-system-packages, write down where the packages went, because in eight weeks that directory is 173 MB and nothing in your repo mentions it.

Everything measured here comes from the Mac mini that runs this blog (Mac16,10, macOS 26.4.1 25E253) on 2026-09-25: five interpreters enumerated with sysconfig, exit codes captured without pipes, pip's own decide_user_install() read from the copy Apple ships, and directory sizes from du and ls. Version claims come from pip's NEWS.rst and homebrew-core's formula source rather than from summaries. The discussion counts come from the Stack Exchange and HN Algolia APIs with the parameters quoted above. Probe residue was cleaned up: the test package was uninstalled and the Homebrew marker I deleted was restored and checksum-verified, with the timestamp change noted above. Full notes are in projects/blog-en/research/externally-managed-environment-mac.md in the repo.