🔧 [FastAPI] uvicorn 실행 시 "OS file watch limit reached" 오류 해결하기

개발 중 FastAPI를 uvicorn --reload 옵션으로 실행하다 보면 아래와 같은 에러를 만날 수 있습니다:

OSError: OS file watch limit reached. about ["/path/to/file"] 
(Error { kind: MaxFilesWatch, paths: [...] })

처음 보면 당황스러울 수 있지만, 이 오류는 운영체제가 감시(watch)할 수 있는 파일 수의 한도를 초과했을 때 발생하는 일반적인 문제입니다.

---

🧠 원인: OS의 파일 감시 수 제한

--reload 옵션은 개발 편의를 위해 파일이 수정되면 서버를 자동으로 재시작합니다. 이 기능은 내부적으로 inotify (Linux) 같은 시스템 감시 기능을 사용합니다.

하지만 OS는 시스템 자원을 보호하기 위해 한 번에 감시 가능한 파일 수 (max_user_watches)에 제한을 둡니다. Python 프로젝트는 보통 가상환경(venv)과 패키지(site-packages)가 많기 때문에 이 한도를 쉽게 초과하게 됩니다.

---

🔍 예시 상황

예를 들어, 다음처럼 uvicorn을 실행했을 때

uvicorn main:app --reload

그리고 프로젝트 구조가 다음과 같다면

.
├── main.py
├── app/
│   └── ...
├── venv/
│   └── ...

uvicorn은 기본적으로 전체 프로젝트 디렉토리를 감시하게 되고, venv 안의 수천 개의 파일도 감시 대상에 포함되어 watch limit 초과가 발생할 수 있습니다.

 

---

✅ 해결 방법 1: 감시 한도 늘리기 (권장)

Linux에서 fs.inotify.max_user_watches 값을 늘려주면 됩니다.

# 현재 감시 한도 확인
cat /proc/sys/fs/inotify/max_user_watches

# 한도 임시 확장 (재부팅 시 초기화됨)
sudo sysctl fs.inotify.max_user_watches=524288

# 영구 설정 (재부팅 후에도 유지)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

🔸 이 설정은 약 100MB 미만의 커널 메모리를 더 사용하지만, 일반적인 개발용 시스템에서는 부담 없는 수준입니다.

---

✅ 해결 방법 2: 감시 디렉터리 제한하기

불필요한 디렉터리를 감시 대상에서 제외하고, 핵심 소스 디렉터리만 감시할 수 있습니다.

uvicorn main:app --reload --reload-dir ./app

 

이렇게 하면 ./app 디렉터리 내부 파일만 감시하고, venv 같은 불필요한 경로는 무시합니다.

---

✅ 해결 방법 3: 프로덕션에서는 --reload 제거

--reload는 개발용 옵션입니다. 운영 환경에서는 제거하세요:

uvicorn main:app --host 0.0.0.0 --port 8000

 

 

✨ 마무리

uvicorn의 reload 기능은 매우 유용하지만, 시스템 리소스를 초과하지 않도록 주의가 필요합니다.

요약:

• 에러는 OS 감시 수 제한 때문에 발생.
• sysctl로 한도 증가하거나, --reload-dir로 감시 범위 제한.
• 운영 환경에서는 --reload 제거!