brew services performs an automatic update of JSON api data when it might not be necessary

[alastair]

brew doctor output

$ brew doctor
Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: Some installed formulae are deprecated or disabled.
You should find replacements for the following formulae:
  node@18
  node@20

but if I uninstall old node just for testing purposes: 

$ brew doctor
Your system is ready to brew.

Verification

• I ran brew update twice and am still able to reproduce my issue.
• My "brew doctor output" above says Your system is ready to brew or a definitely unrelated Tier message.
• This issue's title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

brew config output

HOMEBREW_VERSION: 5.0.5
ORIGIN: https://github.com/Homebrew/brew
HEAD: 70badad488056fb48cf687aa777f2880aac58fe9
Last commit: 2 days ago
Branch: stable
Core tap JSON: 09 Dec 10:56 UTC
Core cask tap JSON: 09 Dec 10:56 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_DOWNLOAD_CONCURRENCY: 28
HOMEBREW_FORBID_PACKAGES_FROM_PATHS: set
HOMEBREW_MAKE_JOBS: 14
Homebrew Ruby: 3.4.7 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/3.4.7/bin/ruby
CPU: 14-core 64-bit arm_brava
Clang: 17.0.0 build 1700
Git: 2.52.0 => /opt/homebrew/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 15.7-arm64
CLT: 26.0.0.0.1.1757719676
Xcode: 26.1.1
Metal Toolchain: N/A
Rosetta 2: false


I don't see any specific other HOMEBREW_* config items in my .bashrc or .profile. I have no ~/.homebrew/ directory. The only HOMEBREW environment variables I have set are

$ env | grep HOMEBREW
HOMEBREW_PREFIX=/opt/homebrew
HOMEBREW_CELLAR=/opt/homebrew/Cellar
HOMEBREW_REPOSITORY=/opt/homebrew

What were you trying to do (and why)?

I use brew services to periodically start and stop services as required depending on what project I'm working on. I normally use this for posgres and redis.

What happened (include all command output)?

When I run a brew services command, I sometimes (but not always) get output of homebrew refreshing some internal data:

$ brew services start postgresql@17
✔︎ JSON API formula_tap_migrations.jws.json         [Downloaded    2.1KB/  2.1KB]
✔︎ JSON API cask_tap_migrations.jws.json            [Downloaded    2.4KB/  2.4KB]
✔︎ JSON API cask.jws.json                           [Downloaded   15.1MB/ 15.1MB]
✔︎ JSON API formula.jws.json                        [Downloaded   31.7MB/ 31.7MB]
==> Successfully started `postgresql@17` (label: homebrew.mxcl.postgresql@17)

This doesn't always happen, so it's clear that this is some sort of periodic refresh of the homebrew internal database. I'm not sure how frequently it does this. If I immediately afterwards run another brew services command, I don't get any output. This only started happening after I upgraded to homebrew 5.

What did you expect to happen?

To me it seems a bit odd that brew services performs this automatic update. If this sub-command is only used for modifying launchctl configuration for already installed software, I'd expect that it doesn't need to do any refresh of the internal database.
Performing the refresh during a brew install or brew upgrade seems fine, and I'm not suggesting this behaviour is changed.
It's not clear to me if this update can be changed to run only in specific subcommands, or for simplicity it's checked every time brew is run.

I don't recall seeing any "updating..." message when using brew services on homebrew 4.

Looking at the environment settings (https://docs.brew.sh/Manpage#environment) I wonder if this is

HOMEBREW_AUTO_UPDATE_SECS
Run brew update once every $HOMEBREW_AUTO_UPDATE_SECS seconds before some commands, e.g. brew install, brew upgrade or brew tap. Alternatively, disable auto-update entirely with $HOMEBREW_NO_AUTO_UPDATE.
Default: 86400 (24 hours), 3600 (1 hour) if a developer command has been run

the "24 hours" default kind of vibes with the frequency with which I see it happen.

What confuses me is that I don't recall making any configuration changes to explicitly use the new API, I understand from the release notes at https://brew.sh/2025/11/12/homebrew-5.0.0/ that this is opt-in at the moment via HOMEBREW_USE_INTERNAL_API and will be enabled at some later time. It's not clear to me if these output messages are in fact from homebrew downloading from the internal API or are from some unrelated code

Step-by-step reproduction instructions (by running brew commands)

brew install postgresql@17
# wait some amount of time (not sure how long? maybe HOMEBREW_AUTO_UPDATE_SECS?)
brew services start postgresql@17

[p-linnane]

This doesn't have anything to do with the new internal API that's in testing. It's as you've described: Homebrew updating on the next brew invocation after the auto-update timeframe has passed.

[Devansh-Jani]

I think the auto-update is being called from brew.sh lines 1078 and 1092, which is a default behaviour from 2022. @p-linnane correct me if I am wrong.

[alastair]

Is it possible then that it's always done this, but that the output has become visible in a recent release?

The documentation snippet that I posted initially says "Run brew update once every $HOMEBREW_AUTO_UPDATE_SECS seconds before some commands, e.g. brew install, brew upgrade or brew tap.", is it possible that this somehow switched from "before some commands" to "before all commands"?

[MikeMcQuaid]

This is HOMEBREW_API_AUTO_UPDATE_SECS not HOMEBREW_AUTO_UPDATE_SECS. It happens more regularly. Work is in progress to make it more efficient/quick.

[alastair]

Thanks @MikeMcQuaid, I did see this config item and tried to wait for 10 minutes (more than 450s) but didn't see any output. I can try again, but maybe it only shows an output if it checks and also if there is new data to download?

I just ran brew services again now (about a day after I last encountered this and opened the issue) and I do see the output. Therefore it seems like this is happening after 24h, rather than HOMEBREW_API_AUTO_UPDATE_SECS (450 seconds, 7 minutes?)

If HOMEBREW_AUTO_UPDATE_SECS only acts on some commands (install, update, as per the docs), does it make sense for HOMEBREW_API_AUTO_UPDATE_SECS to also only act on these commands? IMO it's still surprising that brew services sometimes performs external API requests.

[MikeMcQuaid]

Is it possible then that it's always done this, but that the output has become visible in a recent release?

Yes. We didn't used to always disclose this downloads. We now always do.

but maybe it only shows an output if it checks and also if there is new data to download?

Yes.

This is HOMEBREW_API_AUTO_UPDATE_SECS not HOMEBREW_AUTO_UPDATE_SECS. It happens more regularly. Work is in progress to make it more efficient/quick.

This was wrong, actually. We consider API files stale/outdated after 24h. This could be lengthened.

IMO it's still surprising that brew services sometimes performs external API requests.

I don't think we can ever fully prevent this. We're a rolling release package manager and we are relatively aggressive with deprecations and don't want to support e.g. old JSON file formats indefinitely.

We could potentially bump this from 1 day to e.g. 90 days. Would that resolve your concern @alastair

[alastair]

Thanks @MikeMcQuaid, it sounds like the biggest change here is that something that wasn't previously visible is now being shown during operations. If that's the case, then it sounds like this isn't really a bug, it was just something that I didn't know about previously, and this issue can probably be closed as not a bug.

From my perspective, I don't think that changing 1 day to 90 days is going to affect much on my end - my opinion is that service management for an already installed app shouldn't require performing a periodic update process, however this doesn't bother me too much and I'm able to disable this behaviour myself by disabling auto-update.

Thanks for the responses, and thanks for your work!