launchd plist environment variables: what a job really gets

Line 8 of the script that publishes this blog is a PATH export:

# ops/schedule/daily-content.sh
export PATH="${HOME}/.local/bin:/usr/local/bin:/opt/homebrew/bin:${PATH}"

I inherited that line without a written reason for it, and a line nobody can justify is a line somebody eventually deletes. So I measured what launchd actually hands a job on this machine. The folklore turned out to be right for the wrong reason, the documented answer points at the wrong constant, and the most commonly recommended fix would put the current directory first in PATH for every service in my user domain.

What a launchd job actually receives

I bootstrapped a throwaway agent into gui/501 that did nothing but dump its own environment, then removed it. Machine: Mac16,10 / M4, macOS 26.4.1 (build 25E253), bash 3.2.57. The complete environment, all thirteen variables:

HOME=/Users/sg-mini
LOGNAME=sg-mini
OSLogRateLimit=64
PATH=/usr/bin:/bin:/usr/sbin:/sbin
PWD=/
SHELL=/bin/zsh
SHLVL=1
SSH_AUTH_SOCK=/var/run/com.apple.launchd.bAMFvGwWG4/Listeners
TMPDIR=/var/folders/nw/1f_hl8c90g54vr86ph4dzjth0000gn/T/
USER=sg-mini
XPC_FLAGS=0x0
XPC_SERVICE_NAME=0
_=/usr/bin/env

Three entries are worth stopping on. PATH has four components and lacks /usr/local/bin, even though that is the first line of /etc/paths here; path_helper never ran. LANG is absent, which is the seed of every UnicodeEncodeError that reproduces in a scheduled slot and not in a terminal. And SHELL=/bin/zsh is set even though no shell was involved at any point, so a script cannot test $SHELL to decide whether it got a login environment — that variable describes my account, not the process.

Under that PATH, here is what resolves:

Binary	In the launchd job	In my login shell
claude	not found	/Users/sg-mini/.local/bin/claude
node	not found	—
python3	/usr/bin/python3 — 3.9.6	/opt/homebrew/bin/python3 — 3.14.5
git	/usr/bin/git	/usr/bin/git
curl, jq	/usr/bin/…	same

So line 8 is load-bearing. claude lives in ~/.local/bin, which appears in no system path file, not /etc/paths and nothing in /etc/paths.d/. Delete that export and all ten daily publishing slots die at claude: command not found, while every manual test from a terminal keeps passing.

Where the four-entry PATH comes from

The value is documented, just somewhere nobody looks. man launchd.plist mentions _PATH_STDPATH once, in the section on resolving relative ProgramArguments, and never says it is also the job's PATH. The constant is a header line:

/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/paths.h:67
#define	_PATH_STDPATH	"/usr/bin:/bin:/usr/sbin:/sbin"

Byte-identical to what I measured. Lucas Pinheiro hit the same string when the absence of /usr/local/bin broke an AWS CLI call, but write-ups that report this PATH quote the value without sourcing it, which leaves you unable to predict it on a machine you have not probed.

There is a trap for anyone who tries to look it up properly. man 7 environ does document a default PATH, and says it is /usr/bin:/bin, set "initially by login(1)". That is a different constant defined one line above (_PATH_DEFPATH) describing a different mechanism. Quoting environ(7) at this question gives a confidently wrong two-entry answer.

The failure mode worse than "command not found"

claude: command not found is loud and lands in a log. The quieter case is a binary that resolves to something different. Under launchd, python3 is Python 3.9.6 instead of the 3.14.5 I develop against: five minor versions apart, same command name, no error. It runs in the other direction too, since setting the plist's PATH to /opt/homebrew/bin moved git from /usr/bin/git to /opt/homebrew/bin/git.

I checked whether the interpreter swap currently hurts us, and it does not. Byte-compiling every script under ops/ and ops/analytics/ with both interpreters produced zero syntax failures on each, /usr/bin/python3 ops/analytics/plan.py next ran clean, and grepping for anything 3.10-or-later (match, tomllib, datetime.UTC, except*, PEP 604 unions) returned nothing. The mechanism is real and the damage is hypothetical, and I would rather say so plainly than dress up a near miss as a war story.

Four layers, measured

Setting the plist's EnvironmentVariables PATH to /opt/homebrew/bin gave the job exactly /opt/homebrew/bin, not that directory plus the default. The default was gone. That matters because man launchd.plist describes the key as specifying "additional environmental variables to be set before running the job." The word additional is accurate about the dictionary, which does add keys. For a key that already has a value the value is replaced wholesale, and the man page never tells you what it is replacing. That page is dated 30 July 2019, seven years behind the OS I am running it on.

launchctl setenv applied when the plist key was absent and did not override it when present, matching the documented rule that a service specifying its own PATH takes precedence. It is also read at spawn time rather than at bootstrap: I set a variable after the job was already loaded, ran launchctl kickstart -k, and the job saw the new value.

One more measurement, because it is the mistake I was about to make myself. Variables in the plist are not expanded. I set MMM_TILDE to ~/.local/bin and MMM_DOLLAR_HOME to $HOME/.local/bin, and the job received both as literal strings, tilde and dollar sign intact. A plist PATH containing ~/.local/bin is a dead entry, and that is precisely where the binary I depend on lives.

The recommended fix that puts the current directory in PATH

Searching this problem surfaces launchctl config user path, usually with a warning not to clobber your existing PATH and a safer-looking append. One such page flags the overwrite form as "Bad" and recommends:

launchctl config user path "$(launchctl getenv PATH):/Users/yourname/bin"

On this machine launchctl getenv PATH prints nothing and exits 0. That is the default state, because the backing store at /private/var/db/com.apple.xpc.launchd/config/ is empty. Layer 4 is a compiled-in constant, not a value getenv can hand back. So the recommended command expands to:

:/opt/homebrew/bin

Which fails twice. /usr/bin and its neighbours are gone, and the leading empty entry means the current working directory. I verified that second half rather than assuming it: with PATH=":/usr/bin:/bin", command -v probecwd.sh answered ./probecwd.sh and the script ran; with a trailing colon it also ran; with no empty entry at all it correctly failed with command not found. man bash states the rule directly, that a zero-length directory name in PATH indicates the current directory and may appear as two adjacent colons or as an initial or trailing colon. man execvp adds the history: the default path used to be ":/bin:/usr/bin", and "this was changed to place the current directory last to enhance system security." The recommended fix reintroduces the arrangement that was deliberately removed.

If you land there, delete the key rather than guess at a replacement value: defaults delete /private/var/db/com.apple.xpc.launchd/config/user.plist PathEnvironmentVariable. That recovery comes from an Apple Developer Forums thread where someone ran sudo launchctl config user path PATH with the literal word and lost brew, npm and node from their terminal.

What I do instead, and the gap I found doing it

Our fix lives in the shell scripts rather than the plists. None of our seven com.mmm.* plists set EnvironmentVariables at all. Each runner exports PATH itself and appends the inherited value instead of replacing it, which keeps _PATH_STDPATH intact, survives being run by hand, and keeps the environment contract in the same version-controlled file as the code that depends on it.

Auditing that claim is how I found the hole. The plan I was working from asserted that all our runners export PATH. Five of seven do. ops/schedule/daily-report.sh and ops/telegram/notify.sh do not, and they work today only because the sole binary either one calls is curl, which lives in /usr/bin. That is luck, not design. The day one of them wants Homebrew's jq, or a python3 that has to be 3.14, it will break in a scheduled slot and pass every test I run by hand.

So the ordering is: put PATH in the runner script and append to the inherited value, use the plist's EnvironmentVariables only for genuinely per-job variables, and leave launchctl config user path alone unless you want a domain-wide change and a reboot.

This has the shape of two other things I have measured on this rig. The MCP tools that attach late under headless claude -p and the lock file a power cut leaves behind because trap … EXIT never runs on SIGKILL are both failures a terminal cannot show you, and both sit underneath the guardrails that keep Claude Code running unattended on a schedule and the idempotency guards that stop an LLM cron job double-posting, which assume the runner can find its own binaries. Unattended work fails in the gap between the environment you develop in and the one the scheduler provides, and the cheapest way to close it is to make the scheduler tell you what it hands over. A throwaway agent that runs env and exits took two minutes and retired a question I had been carrying as superstition.

The measurements are first-hand: on 2026-07-30 I bootstrapped two probe agents into gui/501 (macOS 26.4.1, build 25E253, Mac16,10/M4), read their environments, tested PATH precedence between the plist key and launchctl setenv, confirmed ~ and $HOME stay literal, and removed both afterward — our seven real jobs stayed loaded and untouched. The empty-entry and Python 3.9.6-versus-3.14.5 tests were also run locally. Layer 3, launchctl config user path, I did not execute: it needs root and a reboot, so it is reported from man launchctl and the linked thread only. Quotes come from the man pages and paths.h on this machine, linked to a public mirror so you can read them without a Mac. One Apple Support Communities thread returned HTTP 429 on two spaced attempts, so I left it out rather than cite what I could not read.