Developers

Homebrew or npm downloads fail on a Mac

Homebrew downloads with curl and Git. npm downloads from its registry. Each tool reads its own proxy and certificate settings.

Applies to: Current Homebrew and npm on all current macOS versions.Checked: 29 October 2026

Symptoms

  • brew install stops with “curl: (28) … timed out” or “Failed to download resource”.
  • npm install stops with ETIMEDOUT, ECONNRESET or a certificate error.
  • Downloads fail on a company network or VPN only.
  • Downloads start and then stop on a slow connection.

Likely causes

  • A proxy that the tool does not know. Homebrew uses http_proxy, https_proxy and all_proxy. npm uses its proxy and https-proxy settings or the same variables.
  • TLS inspection. A company proxy signs traffic with its own certificate. See Corporate proxy certificates break Terminal tools on a Mac.
  • A wrong npm registry. An old registry setting can point to a server that you cannot reach.
  • A slow or metered connection. Large downloads can time out on a weak Wi-Fi or a hotspot.

How to check

  1. Let Homebrew check your system.

    brew doctor

  2. Show the Homebrew and system configuration.

    brew config

  3. Show npm's registry and proxy settings.

    npm config get registry
npm config get proxy
npm config get https-proxy

  4. Ask the npm registry for a reply.

    npm ping

  5. Test the download host directly with curl.

    curl -v -o /dev/null https://formulae.brew.sh/api/formula.json

How to fix it

  1. For Homebrew behind a proxy, set the proxy variable in the same shell.

    export https_proxy=http://proxy.example.com:8080

  2. For npm behind a proxy, set the npm proxy.

    npm config set https-proxy http://proxy.example.com:8080

  3. Remove an old npm registry setting so npm uses its default.

    npm config delete registry

  4. Let Homebrew try a failed download more times.

    export HOMEBREW_CURL_RETRIES=5

  5. If your company uses a mirror, set it. Homebrew uses HOMEBREW_BOTTLE_DOMAIN and HOMEBREW_API_DOMAIN for mirrors.

  6. For certificate errors, add the company root certificate. See Corporate proxy certificates break Terminal tools on a Mac.

With Kilobat

  1. Before a big install, check whether the network is metered, on a VPN or slow.

    kilobat conditions

  2. Find the layer that stops the download host. Add --app to use the proxy variables of that process.

    kilobat why https://ghcr.io/v2/homebrew/core --app process:curl

  3. Keep the Mac awake while the install runs.

    kilobat awake -- brew upgrade

  4. These commands are free. See Check the network before a big download in an agent.

Questions

Does Homebrew use the System Settings proxy?

Homebrew's documentation lists proxy variables for curl, Git and Subversion. Set https_proxy in your shell.

How long does npm wait?

npm's documentation gives a default fetch-timeout of 300000 ms, five minutes, and 2 fetch-retries.

Sources

Sources checked on 29 October 2026. Man pages are the ones installed with macOS; open one with man <name> in Terminal.