포트 이미 사용중 해결 — EADDRINUSE / port already in use 잡는 법 | CodeMaster 블로그

증상: port already in use / EADDRINUSE

서버를 실행하는 순간 이런 에러가 나면서 죽습니다.

Error: listen EADDRINUSE: address already in use :::3000

# 다른 표현
OSError: [Errno 98] Address already in use   (Python)
Port 3000 is already in use

뜻은 명확합니다. "내가 쓰려는 포트(3000)를 이미 다른 프로세스가 차지하고 있다". 한 포트는 한 순간에 한 프로세스만 listen할 수 있기 때문입니다. EADDRINUSE는 Node.js가, Address already in use는 OS·파이썬이 같은 상황을 다르게 표현한 것뿐, 원인과 해결은 동일합니다. 마지막의 숫자(:::3000의 3000)가 충돌한 포트 번호입니다.

왜 EADDRINUSE가 나는가

이전 서버가 안 죽음 — 터미널을 강제로 닫거나 크래시 후 프로세스가 좀비로 남음. 가장 흔합니다.
같은 포트로 두 번 실행 — 다른 탭에서 이미 같은 앱을 돌리는 중.
다른 프로그램이 포트 점유 — 5000번을 macOS AirPlay가 쓰는 등.
nodemon 중복 재시작 — 빠른 저장으로 인스턴스가 겹침.

케이스별 해결

1) 점유 프로세스를 찾아 종료 (정석)

두 단계입니다. 먼저 그 포트를 쓰는 프로세스의 PID를 찾고, 그다음 종료합니다.

macOS / Linux

lsof -i :3000          # 포트를 쓰는 PID와 프로세스 이름 확인
kill -9 <PID>          # 해당 프로세스 종료

# 한 줄로 (찾자마자 종료)
kill -9 $(lsof -t -i:3000)

lsof 출력의 COMMAND 열에서 그게 정말 내 개발 서버(node, python 등)인지 한 번 확인하고 종료하면 안전합니다.

Windows (PowerShell / cmd)

netstat -ano | findstr :3000    # 맨 끝 숫자가 PID
taskkill /PID <PID> /F

# PowerShell이면 더 간단
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess

2) 포트를 바꿔서 실행

점유 프로세스가 꼭 필요한 것이라면 내 앱의 포트를 바꿉니다.

# 환경변수로
PORT=3001 npm run dev          # macOS/Linux
set PORT=3001 && npm run dev    # Windows cmd
$env:PORT=3001; npm run dev     # PowerShell

코드에서 직접:

const port = process.env.PORT || 3001;
app.listen(port);

3) macOS 5000번 포트

macOS 최신 버전은 AirPlay 수신이 5000번을 씁니다. 앱 포트를 바꾸거나, 시스템 설정 → 일반 → AirDrop 및 Handoff에서 AirPlay 수신을 끄세요.

4) Docker 컨테이너 점유

로컬 프로세스는 안 보이는데 계속 점유되어 있다면, 백그라운드 Docker 컨테이너가 포트를 매핑하고 있을 수 있습니다.

docker ps                # 포트 매핑(0.0.0.0:3000->...) 확인
docker stop <컨테이너ID>

5) nodemon / 핫리로드 중복

nodemon이나 개발 서버가 빠른 저장으로 이전 인스턴스를 다 못 죽인 채 새로 띄우면 잠깐 충돌이 납니다. 이 경우 모든 node 프로세스를 정리하고 다시 시작하면 깔끔합니다. macOS/Linux는 pkill -f node, Windows는 작업 관리자에서 node 프로세스를 종료하면 됩니다. (단, 다른 중요한 node 작업이 없을 때만.)

OS별 명령어 비교

작업	macOS / Linux	Windows
점유 PID 찾기	lsof -i :3000	netstat -ano \| findstr :3000
프로세스 종료	kill -9 PID	taskkill /PID PID /F
포트 변경	PORT=3001 ...	$env:PORT=3001; ...

예방

서버 종료는 터미널 강제 닫기 대신 Ctrl+C로 깔끔하게.
포트는 환경변수로 받아 충돌 시 바꾸기 쉽게 설계.
여러 서비스를 동시에 돌린다면 포트 번호 규칙을 문서화.
nodemon 사용 시 저장 후 재시작이 끝날 때까지 기다리기.

자주 묻는 질문

Q1. kill -9를 써도 괜찮나요?

개발 서버라면 대체로 괜찮습니다. 다만 -9(SIGKILL)는 정리 없이 즉시 종료하므로, 가능하면 먼저 일반 kill <PID>를 시도하고 안 죽을 때만 -9를 쓰세요.

Q2. 분명히 껐는데도 계속 in use라고 떠요.

좀비 프로세스나 다른 탭에서 같은 앱이 도는 경우입니다. lsof -i :포트/netstat로 실제 점유 PID를 확인해 직접 종료하면 해결됩니다.

Q3. PID를 죽이는 게 위험하진 않나요?

먼저 그 PID가 내 개발 프로세스(node 등)인지 확인하세요. lsof 출력의 프로세스 이름을 보고 시스템 핵심 프로세스가 아니면 종료해도 안전합니다.