---
title: "Mac의 npm 오류 코드 ETIMEDOUT: npm 네트워크 시간 초과 해결하기 · Kilobat 가이드"
url: "https://kilobat.app/ko/guides/npm-etimedout"
description: "Mac에서 npm install이 npm error code ETIMEDOUT으로 중단됩니다. 레지스트리, 프록시 및 연결을 확인한 다음 npm 설정을 변경하세요."
---

오류 메시지

# Mac에서 “npm error code ETIMEDOUT” 발생

ETIMEDOUT은 상대방이 제때 응답하지 않았다는 뜻입니다. Node.js 문서는 “연결된 상대방이 일정 시간 후에도 제대로 응답하지 않았습니다”라고 설명합니다.

적용 대상: npm 10 이상은 “npm error”를 출력합니다. 이전 버전은 “npm ERR!”를 출력합니다. 현재 지원되는 모든 macOS 버전. · 확인일: 2026년 10월 29일

## 증상

- `npm install`이(가) `npm error code ETIMEDOUT` 메시지와 함께 중단됩니다.
- npm은 이 문제가 네트워크 연결과 관련되어 있다고 덧붙입니다.
- 회사 네트워크나 핫스팟 같은 특정 네트워크에서 실패합니다.

## 가능한 원인

- **npm에 설정되지 않은 프록시.** 프록시가 필요한 네트워크에서는 npm의 `proxy` 및 `https-proxy` 설정이 필요합니다.
- **연결할 수 없는 레지스트리.** 오래된 `registry` 설정이 개인 서버를 가리킬 수 있습니다.
- **느리거나 패킷 손실이 있는 연결.** Wi-Fi 신호가 약하거나 핫스팟을 사용하면 큰 패키지의 다운로드 시간이 초과될 수 있습니다.
- **작동하지 않는 IPv6 경로.** 레지스트리에 IPv6 주소가 있지만 네트워크에서 IPv6가 작동하지 않습니다.

## 확인 방법

1. npm의 레지스트리 및 프록시 설정을 표시합니다.

   ```
   npm config get registry
   npm config get proxy
   npm config get https-proxy
   ```
2. 레지스트리에 응답을 요청하세요.

   ```
   npm ping
   ```
3. curl을 사용하여 IPv4만으로 레지스트리를 테스트하세요.

   ```
   curl -4 -I https://registry.npmjs.org/
   ```
4. 연결을 측정합니다.

   ```
   networkQuality
   ```

## 해결 방법

1. 네트워크에 프록시가 필요하면 npm에 설정하세요.

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

   ```
   npm config delete registry
   ```
3. 느린 연결에서 npm의 재시도 횟수를 늘립니다.

   ```
   npm config set fetch-retries 5
   ```
4. 가능하면 더 빠른 네트워크에서 설치를 다시 실행하세요.

## Kilobat 사용

1. Kilobat 연결 진단은 네트워크, 프록시, DNS, 규칙, IPv4, IPv6, TLS 및 서버 순으로 레지스트리를 테스트합니다. 실패한 계층을 알려줍니다.

   ```
   kilobat why https://registry.npmjs.org/
   ```
2. 대규모 설치 전에 네트워크의 데이터 제한, VPN 연결 및 속도를 확인합니다.

   ```
   kilobat conditions
   ```
3. 이 Kilobat 검사는 무료입니다. AI 에이전트는 MCP를 통해 `diagnose_connection` 및 `diagnose_network`(으)로 실행합니다. [특정 사이트나 API에 연결되지 않는 이유 찾기](https://kilobat.app/ko/guides/recipes/why-cant-it-connect)를 참조하세요.

## 질문

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

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

**프록시 설정이 npm 다운로드에 영향을 줄 수 있나요?**

예. npm에는 프록시 구성이 있으며, 접근할 수 없거나 잘못된 프록시는 레지스트리 연결을 방해할 수 있습니다.

## 출처

- [Node.js 문서: 일반적인 시스템 오류](https://nodejs.org/api/errors.html#common-system-errors)
- [npm 문서: config](https://docs.npmjs.com/cli/v11/using-npm/config)
- curl(1) 및 networkQuality(8), macOS 27.2와 함께 설치된 매뉴얼 페이지

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

## 관련 가이드

- [Mac에서 “npm error code ECONNRESET”](https://kilobat.app/ko/guides/npm-econnreset): ECONNRESET은 강제로 재설정된 연결을 나타냅니다.
- [Mac에서 Homebrew 또는 npm 다운로드 실패](https://kilobat.app/ko/guides/homebrew-npm-download-fails): Homebrew는 curl과 Git으로 다운로드합니다.
- [프록시 설정으로 인해 Mac에서 앱이 연결되지 않습니다](https://kilobat.app/ko/guides/proxy-settings-breaking-apps): 프록시 설정은 다른 서버를 통해 트래픽을 전송합니다.
- [회사 프록시 인증서로 인해 Mac의 터미널 도구가 작동하지 않음](https://kilobat.app/ko/guides/corporate-proxy-certificates): 일부 회사 네트워크는 HTTPS 트래픽을 검사합니다.
- [에이전트의 대용량 다운로드 전에 네트워크 확인](https://kilobat.app/ko/guides/recipes/check-network-before-download): 에이전트는 지금이 대용량 전송에 적합한 시점인지 Kilobat에 물어볼 수 있습니다.