2026-07-27 10:26:30 -04:00
2 changed files with 3 additions and 3 deletions
@@ -79,7 +79,7 @@ The installer is a bootstrapper: it finds a suitable Python, installs bot-bottle

 ### Requirements

-**Python ≥ 3.11**, and this is the one that trips people up on macOS: the `python3` Apple ships at `/usr/bin/python3` is **3.9.6**, which is too old. A Homebrew or python.org Python is only on your `PATH` because of a line in your shell profile, so anything running without that profile — a fresh user account, a launchd job, a CI runner — sees the 3.9 stub instead. The installer therefore looks past `PATH` before giving up: it tries `python3`, then `python3.11`–`python3.14`, then `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, and python.org framework builds, and tells you which one it picked when it isn't the obvious one. Point it somewhere specific with `BOT_BOTTLE_PYTHON=/path/to/python3`.
+**Python ≥ 3.11**, and this is the one that trips people up on macOS: the `python3` Apple ships at `/usr/bin/python3` is **3.9.6**, which is too old. Bare `python3` resolves to that stub far more often than people expect. `path_helper` builds a login shell's `PATH` from `/etc/paths` and then appends `/etc/paths.d/*`, and `/usr/bin` sits in the former — so even when `/opt/homebrew/bin` *is* on the `PATH` (via `/etc/paths.d/homebrew`), it comes after `/usr/bin` and loses. Prepending a newer Python is something your shell profile does, and a fresh account, a launchd job, or a CI runner has no such profile. So the installer looks past bare `python3` before giving up: it tries `python3`, then the versioned `python3.11`–`python3.14` names, then `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, and python.org framework builds — and tells you which one it picked when it isn't the obvious one. Point it somewhere specific with `BOT_BOTTLE_PYTHON=/path/to/python3`.

 **`pipx`** is strongly preferred over the `pip --user` fallback. Homebrew and Debian/Ubuntu interpreters are externally managed (PEP 668), which blocks `pip install --user` outright; the installer detects this and tells you to install `pipx` rather than failing deep inside pip.

@@ -4,8 +4,8 @@
 # Exercises install.sh the way a brand-new user would, inside a throwaway
 # macOS account you create and delete from the CLI. install.sh's entire
 # footprint is user-home-local — the pipx venv under ~/.local (or the pip
-# --user tree under ~/Library/Python), the ~/.bot-bottle config dir, and a
-# PATH line in the login shell. It never installs the backend itself (see
+# --user tree under ~/Library/Python) and the ~/.bot-bottle config dir. It
+# writes no shell-profile PATH line, and never installs the backend (see
 # the header of install.sh), so deleting the user is a complete,
 # deterministic reset of everything the installer touched. The Apple
 # `container` runtime is a HOST prerequisite installed once and kept;