---
title: "Mac에서 brew install 또는 npm install이 네트워크 오류로 실패하는 경우 · Kilobat 가이드"
url: "https://kilobat.app/ko/guides/homebrew-npm-download-fails"
description: "brew install 또는 npm install이 시간 초과, 프록시 또는 인증서 오류로 중단되는 이유를 찾고 네트워크에 필요한 프록시, 미러 또는 인증서를 설정하세요."
---

개발자

# Mac에서 Homebrew 또는 npm 다운로드 실패

Homebrew는 curl과 Git으로 다운로드합니다. npm은 자체 레지스트리에서 다운로드합니다. 각 도구는 자체 프록시와 인증서 설정을 읽습니다.

적용 대상: 현재 모든 macOS 버전에서 사용하는 최신 Homebrew 및 npm. · 확인일: 2026년 10월 29일

## 증상

- `brew install`이(가) “curl: (28) … timed out” 또는 “Failed to download resource” 오류와 함께 중지됩니다.
- `npm install`이 ETIMEDOUT, ECONNRESET 또는 인증서 오류를 표시하며 중단됩니다.
- 회사 네트워크 또는 VPN에서만 다운로드가 실패합니다.
- 느린 연결에서 다운로드가 시작된 후 중지됩니다.

## 가능한 원인

- **도구에 설정되지 않은 프록시.** Homebrew는 `http_proxy`, `https_proxy`, `all_proxy`을 사용합니다. npm은 자체 `proxy` 및 `https-proxy` 설정이나 같은 변수를 사용합니다.
- **TLS 검사.** 회사 프록시가 자체 인증서로 트래픽에 서명합니다. [회사 프록시 인증서로 인해 Mac의 터미널 도구가 작동하지 않는 경우](https://kilobat.app/ko/guides/corporate-proxy-certificates)를 참고하세요.
- **잘못된 npm 레지스트리.** 오래된 `registry` 설정이 연결할 수 없는 서버를 가리킬 수 있습니다.
- **느리거나 데이터가 제한된 연결.** Wi-Fi 신호가 약하거나 핫스팟을 사용할 때 대용량 다운로드가 시간 초과될 수 있습니다.

## 확인 방법

1. Homebrew로 시스템을 확인합니다.

   ```
   brew doctor
   ```
2. Homebrew 및 시스템 구성을 표시합니다.

   ```
   brew config
   ```
3. npm의 레지스트리 및 프록시 설정을 표시합니다.

   ```
   npm config get registry
   npm config get proxy
   npm config get https-proxy
   ```
4. npm 레지스트리에 응답을 요청합니다.

   ```
   npm ping
   ```
5. curl로 다운로드 호스트를 직접 테스트하세요.

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

## 해결 방법

1. 프록시 뒤에서 Homebrew를 사용하려면 같은 셸에서 프록시 변수를 설정하세요.

   ```
   export https_proxy=http://proxy.example.com:8080
   ```
2. 프록시 뒤의 npm에는 npm 프록시를 설정하세요.

   ```
   npm config set https-proxy http://proxy.example.com:8080
   ```
3. npm이 기본 레지스트리를 사용하도록 이전 npm 레지스트리 설정을 제거합니다.

   ```
   npm config delete registry
   ```
4. Homebrew가 실패한 다운로드를 더 많이 재시도하도록 합니다.

   ```
   export HOMEBREW_CURL_RETRIES=5
   ```
5. 회사에서 미러를 사용한다면 설정하세요. Homebrew는 미러에 `HOMEBREW_BOTTLE_DOMAIN` 및 `HOMEBREW_API_DOMAIN`을 사용합니다.
6. 인증서 오류가 발생하면 회사 루트 인증서를 추가하세요. [회사 프록시 인증서로 Mac의 터미널 도구가 작동하지 않는 경우](https://kilobat.app/ko/guides/corporate-proxy-certificates)를 참고하세요.

## Kilobat 사용

1. 대규모 설치 전에 네트워크가 데이터 요금제 연결인지, VPN을 사용하는지, 속도가 느린지 확인하세요.

   ```
   kilobat conditions
   ```
2. 다운로드 호스트로의 연결을 막는 계층을 찾습니다. 해당 프로세스의 프록시 변수를 사용하려면 `--app`를 추가하세요.

   ```
   kilobat why https://ghcr.io/v2/homebrew/core --app process:curl
   ```
3. 설치가 실행되는 동안 Mac을 깨워 둡니다.

   ```
   kilobat awake -- brew upgrade
   ```
4. 이 명령들은 무료입니다. [에이전트에서 대용량 다운로드 전 네트워크 확인하기](https://kilobat.app/ko/guides/recipes/check-network-before-download)를 참고하세요.

## 질문

**Homebrew가 시스템 설정의 프록시를 사용하나요?**

Homebrew 문서에는 curl, Git, Subversion의 프록시 변수가 나와 있습니다. 셸에서 `https_proxy`를 설정하세요.

**npm은 얼마나 기다리나요?**

npm 문서에 따르면 기본 `fetch-timeout`은 300000 ms, 즉 5분이며 `fetch-retries`은 2입니다.

## 출처

- [Homebrew 문서: 매뉴얼 페이지, 환경 변수](https://docs.brew.sh/Manpage)
- [npm 문서: config](https://docs.npmjs.com/cli/v11/using-npm/config)
- curl(1), macOS 27.2에 설치된 매뉴얼 페이지

2026년 10월 29일 확인했습니다.

## 관련 가이드

- [회사 프록시 인증서로 인해 Mac의 터미널 도구가 작동하지 않음](https://kilobat.app/ko/guides/corporate-proxy-certificates): 일부 회사 네트워크는 HTTPS 트래픽을 검사합니다.
- [프록시 설정으로 인해 Mac에서 앱이 연결되지 않습니다](https://kilobat.app/ko/guides/proxy-settings-breaking-apps): 프록시 설정은 다른 서버를 통해 트래픽을 전송합니다.
- [에이전트의 대용량 다운로드 전에 네트워크 확인](https://kilobat.app/ko/guides/recipes/check-network-before-download): 에이전트는 지금이 대용량 전송에 적합한 시점인지 Kilobat에 물어볼 수 있습니다.
- [Mac에서 SSH와 Git 연결 시간 초과](https://kilobat.app/ko/guides/ssh-git-timeouts): SSH와 Git에는 서버에 정상적으로 연결되는 TCP 연결이 필요합니다.
- [Mac에서 “npm error code ETIMEDOUT” 발생](https://kilobat.app/ko/guides/npm-etimedout): ETIMEDOUT은 상대방이 제때 응답하지 않았음을 의미합니다.