envsubst on Mac: Not Built In, and 5 Ways It Prints Blanks

On a clean shell with only Apple's directories in PATH, macOS 26.4.1 answers envsubst with zsh:1: command not found: envsubst and exit code 127. Bash says the same thing. Yet the Mac mini that runs this business has a working envsubst at /opt/homebrew/bin/envsubst, and I never asked for it. Homebrew installed it on 2026-05-15 as part of gettext, with installed_on_request: false, because 24 of the formulas on this machine depend on gettext, git and wget among them.

So "envsubst on Mac" is really two questions. How do you get it, and why does it quietly print blanks once you have it? I ran both on macOS 26.4.1 (build 25E253) with GNU gettext 1.0, the version Homebrew ships today.

Why envsubst is missing on a Mac

envsubst isn't a shell builtin or a POSIX tool. It's one of the small programs in GNU gettext, the translation library that Linux distributions install early because so much else needs it. That's why a Dockerfile or CI script that works on Ubuntu breaks on a Mac. Apple doesn't ship gettext. The only gettext-like names in /usr/bin, /bin, /usr/sbin and /sbin are two Perl scripts, xgettext.pl and xgettext5.34.pl, and neither one substitutes variables.

The most-viewed Stack Overflow question on this, "envsubst: command not found on Mac OS X 10.8" (106,335 views), has a 293-point answer that says to run brew install gettext and then brew link --force gettext. You don't need the second command anymore. The current gettext formula has no keg_only line, and on this Mac the symlink went into /opt/homebrew/bin without it:

$ brew install gettext        # 2,499 files, 35.3 MB installed
$ ls -l /opt/homebrew/bin/envsubst
lrwxr-xr-x  1 sg-mini  admin  34 May 15 14:01 /opt/homebrew/bin/envsubst -> ../Cellar/gettext/1.0/bin/envsubst
$ envsubst --version | head -1
envsubst (GNU gettext-runtime) 1.0

If you have Homebrew's git, wget, gawk or poppler, run which envsubst before you install anything. Each of those four has gettext in its dependency tree, so you may already have it, like I did.

What envsubst replaces, and what it leaves alone

The GNU manual is short. envsubst copies standard input to standard output and replaces $VARIABLE and ${VARIABLE} with values from the environment. Nothing else. ${variable-default}, $(command) and backticks are skipped "due to security reasons." It also has no escape character. Here's every case I tried, with HOME=/Users/x and HOST=web1 exported:

To see what came up in practice, I pulled every Stack Overflow question with "envsubst" in the title through the Stack Exchange API: 34 questions, 382,924 views in total. Sorted by title, 2 are "command not found" (123,658 views), 4 are about a file that came out empty, 3 are about values coming out blank, 2 are about escapes or defaults, and 11 are Docker, nginx or CI wiring. The other 12 didn't fit a bucket. The five traps below are the mechanics behind the first four groups.

Trap 1: the variable is set but not exported

envsubst is a separate process, so it only sees exported variables. A plain assignment in your shell doesn't count:

$ TOKEN=abc123; echo 'tok=[$TOKEN]' | envsubst
tok=[]
$ export TOKEN; echo 'tok=[$TOKEN]' | envsubst
tok=[abc123]

This one hits me in particular. The .env file this business runs on has no export lines, so source .env sets every key without exporting any of them. The fix I already use for Python works here too: set -a; source .env; set +a. With that, the same probe printed k=[sk-test-1] instead of k=[]. It's the same idea as launchd plist environment variables: a value you can see in your shell isn't necessarily in the child's environment.

Trap 2: it ate the nginx variables

An unset variable becomes an empty string, not an error. That's how nginx configs get broken. With no argument, envsubst replaces every $name, including nginx's own $host and $remote_addr:

$ printf 'server_name $HOST;\nproxy_set_header Host $host;\n' | envsubst
server_name web1;
proxy_set_header Host ;
$ printf 'server_name $HOST;\nproxy_set_header Host $host;\n' | envsubst '$HOST'
server_name web1;
proxy_set_header Host $host;

The optional argument is a list of the variables you want replaced, and everything else passes through. The official nginx image's entrypoint does this: it builds a ${NAME} list from the variables that are actually defined (optionally narrowed by NGINX_ENVSUBST_FILTER) and passes it as that argument. Run envsubst --variables '$HOST ${PORT:-80} $$W' to see what a filter string covers. Here it prints HOST and W, and PORT is missing because ${PORT:-80} isn't a form envsubst understands.

Trap 3: the argument isn't a file

envsubst template.conf looks right and exits 0, but it doesn't read the file. The argument is the variable list from trap 2. With nothing on standard input, the output was empty. With input piped in, it treated the file name as a filter that matches no variables, so the input came back unchanged. Two arguments get envsubst: too many arguments and exit 1. The file always goes in on standard input: envsubst < template.conf.

Trap 4: the file is now 0 bytes

$ envsubst < tpl.conf > tpl.conf
$ stat -f %z tpl.conf
0

The shell truncates tpl.conf for the > before envsubst reads it. Piping through tee doesn't fix this. It only makes it random, because both processes start together. On Linux you'd reach for sponge or for cp --attributes-only from an often-copied answer. sponge isn't installed on a Mac, and Apple's /bin/cp rejects the flag with illegal option -- - and exit 64. What works with only stock tools is a temp file and a rename, or reading into a variable first:

tmp=$(mktemp) && envsubst < tpl.conf > "$tmp" && mv "$tmp" tpl.conf

BSD sed -i has its own Mac version of this problem, covered in sed: invalid command code.

Trap 5: defaults and escapes don't exist

${PORT:-80} passes through unchanged, so at least the mistake is visible in the output. Escapes are worse. \$HOME became \/Users/x (the backslash stays and the variable is still expanded), and $$HOME became $/Users/x. The only reliable way to keep a literal $NAME is the filter argument from trap 2. If you want shell-style defaults, give the variable a value in the call, as in PORT="${PORT:-80}" envsubst < tpl, or use a8m/envsubst, a Go rewrite (907 stars) that supports ${VAR:-default}.

No Homebrew? Two stock substitutes

macOS has /usr/bin/perl 5.34.1, and /usr/bin/python3 3.9.6 once the Command Line Tools are installed. Each one can do the basic substitution in one line:

perl -pe 's/\$\{(\w+)\}/$ENV{$1}/g' < tpl.conf
python3 -c 'import os,sys,string;sys.stdout.write(string.Template(sys.stdin.read()).safe_substitute(os.environ))' < tpl.conf

They're not drop-in replacements. The Perl version only handles the braced form, and it also blanks unknown names. Python's safe_substitute leaves unknown names alone ($NOPE came back as $NOPE), which is the opposite of envsubst. Speed isn't a reason to choose either way. envsubst got through a 1,044,000-byte template in 0.02 seconds. If a script also needs timeout, the other GNU tool Macs don't have, timeout: command not found on Mac covers the same Homebrew-versus-stock choice.

FAQ

How do I install envsubst on a Mac?

Run brew install gettext. envsubst is part of GNU gettext, which macOS doesn't include. With the current Homebrew formula, the binary is linked into /opt/homebrew/bin automatically, so the old brew link --force gettext step isn't needed. If you already have Homebrew's git or wget, gettext is probably installed as a dependency. Check with which envsubst first.

Why does envsubst output empty values?

envsubst only reads exported environment variables, and it replaces any variable that isn't set with an empty string. Export the variable, or wrap source .env in set -a and set +a, and pass a list such as envsubst '$HOST' so that names you didn't mean to replace, like nginx's $host, are left alone.

Does envsubst support default values like ${VAR:-default}?

No. GNU envsubst only replaces $VAR and ${VAR} and leaves ${VAR:-default} unchanged in the output. Set the default when you call it, for example PORT="${PORT:-80}" envsubst < template, or use a reimplementation such as a8m/envsubst that supports defaults.

How this was checked: every command and output above was run on 2026-10-15 on a Mac mini M4 running macOS 26.4.1 (build 25E253). envsubst is GNU gettext-runtime 1.0 from Homebrew. The "command not found" result used a clean environment (env -i, zsh -f and bash --noprofile --norc) with only Apple's four bin directories in PATH. Install date, dependency status and the 24 dependent formulas come from brew info --json=v2 and brew uses --installed on this machine. The Stack Overflow figures come from the Stack Exchange API title search on the same day, sorted by title only. The nginx behavior comes from reading the image's entrypoint script, not from running the container.