Documentation for ~/.homebrew/brew.env incorrect?

[jcwren]

Output of brew config

HOMEBREW_VERSION: 4.5.6
ORIGIN: https://github.com/Homebrew/brew
HEAD: 7b4ef99fed96966269ee35994407fa4c06097a4d
Last commit: 6 days ago
Branch: stable
Core tap JSON: 15 Jun 13:14 UTC
Core cask tap JSON: 15 Jun 13:14 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_MAKE_JOBS: 8
HOMEBREW_NO_ENV_HINTS: set
Homebrew Ruby: 3.4.4 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/3.4.4/bin/ruby
CPU: octa-core 64-bit arm_blizzard_avalanche
Clang: 17.0.0 build 1700
Git: 2.39.5 => /Library/Developer/CommandLineTools/usr/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 15.5-arm64
CLT: 16.4.0.0.1.1747106510
Xcode: N/A
Rosetta 2: false

Output of brew doctor

Your system is ready to brew.

Description of issue

I was trying to figure out why homebrew wasn't picking up setting HOMEBREW_NO_ENV_HINTS from my ~/.homebrew/brew.env file. When I set it in .zprofile, it worked as expected. Like any good user, I read the man page, which I've included below. My initial attempt was

export HOMEBREW_NO_ENV_HINTS=1

just like the man page says. No errors, but also not setting the variable. After some searching I found an old discussion that indicated the brew.env file is a key-value format, I removed the export and it worked. As a test, I removed the =, and got the following error, so I knew it was attempting to process the file.

/opt/homebrew/bin/brew: line 139: export: `HOMEBREW_NO_ENV_HINTS 1': not a valid identifier

man brew says the following for the ENVIRONMENT section. Nowhere can I find anything that says the file should be in a key-value format. The only place key occurs in the man page is for the option --keyboard-layoutdir in the GLOBAL CASK OPTIONS section.

Before I file an issue, my question is should the man page be updated to indicate the brew.env files should NOT have export preceding the variable name? Or should the brew command either ignore the export keyword or perhaps treat it as an error?

ENVIRONMENT
       Note that environment variables must have a value set to be detected. For example, run export HOMEBREW_NO_INSECURE_REDIRECT=1 rather than just export HOMEBREW_NO_INSECURE_REDIRECT.

       HOMEBREW_* environment variables can also be set in Homebrew’s environment files:

       •   /etc/homebrew/brew.env (system-wide)

       •   ${HOMEBREW_PREFIX}/etc/homebrew/brew.env (prefix-specific)

       •   $XDG_CONFIG_HOME/homebrew/brew.env if $XDG_CONFIG_HOME is set or ~/.homebrew/brew.env otherwise (user-specific)

       User-specific environment files take precedence over prefix-specific files and prefix-specific files take precedence over system-wide files (unless $HOMEBREW_SYSTEM_ENV_TAKES_PRIORITY is set, see below).

       Note that these files do not support shell variable expansion e.g. $HOME or command execution e.g. $(cat file).

[arnavk23]

Thanks for the clear breakdown, @jcwren — you're absolutely right to question this.

The documentation is currently misleading:
Despite the man page showing examples using export, the ~/.homebrew/brew.env file is not a shell script — it must follow a simple key=value format without export, or it will silently fail or throw a parsing error.

The file is parsed internally by brew shellenv (not sourced as a script), so lines like:

export HOMEBREW_NO_ENV_HINTS=1

are treated as invalid. This is why:

HOMEBREW_NO_ENV_HINTS=1

works, while the export version fails.

You discovered this by manually removing the export and observing correct behavior — and that's exactly the right fix.

Docs are missing this key point

The current man brew description:

“HOMEBREW_* environment variables can also be set in Homebrew’s environment files: [...]”

...does not mention:

• The required format (no export)
• That it's not parsed as a shell script
• That using export will break the behavior silently or with a vague error

Suggestion:

Yes — I agree the man page should be clarified. It could say something like:

“The brew.env files use a simple KEY=value format. Do not prefix variables with export or include shell commands, as these files are not sourced as scripts.”

Alternatively, brew could emit a clearer error if export is detected in the file.

[SMillerDev]

Don't hesitate to make a pull request to that extent. People robbing into problems and proposing fixes for them is what makes open source projects so great.