이 책의 환경을 실제로 구축하면서 만난 빨간 에러들을 증상·원인·해결로 정리했습니다. 대부분은 본편에서 한 번씩 다뤘지만, 막혔을 때 한곳에서 빠르게 찾도록 모았습니다. 증상 메시지로 이 장을 검색하면 바로 해결로 갈 수 있습니다.

dlib·OpenCV (conda)

증상: pip install dlib이 CMake·컴파일러 에러로 실패 원인: dlib은 C++ 빌드가 필요(PART 01 Ch01). 해결: conda-forge 프리빌트 사용.

conda install -c conda-forge "dlib>=20" "opencv=4.*"

증상: AttributeError: module 'cv2' has no attribute 'data' 원인: conda-forge opencv에는 cv2.data가 없음(pip opencv-python에만 있음, PART 02 Ch02). 해결: haar 경로를 직접 찾는다.

import os, sys, glob, cv2name = "haarcascade_frontalface_default.xml"hits = glob.glob(os.path.join(sys.prefix, "share", "opencv*", "haarcascades", name))detector = cv2.CascadeClassifier(hits[0])

증상: cv2.dnn.readNetFromCaffe가 없거나 동작 안 함 원인: conda-forge 기본 OpenCV 5.0이 Caffe 임포터·cv2.data를 제거. 해결: opencv=4.* 고정(PART 01 Ch03).

증상: dlib 검출 시 RuntimeError: Unsupported image type, must be 8bit gray or RGB image 원인: NumPy 2.x + 구 dlib(numpy1 빌드) ABI 충돌. 해결: conda install -c conda-forge "dlib>=20"(PART 01 Ch04).

TensorFlow·DeepFace·RetinaFace

증상: ValueError: ... requires tf-keras package 원인: 최신 TensorFlow는 Keras 3 기본인데 DeepFace·RetinaFace는 Keras 2 필요(PART 06 Ch05). 해결: pip install tf-keras.

증상: DeepFace/InsightFace 첫 호출이 매우 느림 원인: 가중치를 그때 다운로드(~/.deepface, ~/.insightface). 정상. 해결: 서버는 시작 시 워밍업, 오프라인은 가중치 미리 복사(PART 06·11).

onnxruntime·Apple Silicon

증상: GPU를 지정했는데 빨라지지 않음 원인: 해당 provider가 없어 조용히 CPU로 폴백(PART 07·11). 해결: onnxruntime.get_available_providers()로 활성 provider 확인, CUDA는 onnxruntime-gpu 필요.

증상: Apple Silicon 맥에서 TensorFlow 가속이 안 됨 원인: 기본 TF는 CPU. 해결: 학습 단계는 CPU로 두거나, ONNX 계열(InsightFace)로 CoreML provider 활용(PART 07 Ch03).

conda·pip 환경 꼬임

증상: conda create가 CondaToSNonInteractiveError(defaults 채널 ToS) 원인: conda 26.x가 기본 채널 ToS 동의 요구. 해결: conda-forge 전용으로.

conda create -n face -c conda-forge --override-channels python=3.11

증상: 패키지를 깔았는데 환경에서 import가 안 됨 원인: conda env에 pip이 없어 conda run -n env pip이 base에 설치. 해결: env에 pip을 먼저 깔고 그 env의 python으로 설치.

conda install -n face pip~/miniconda3/envs/face/bin/python -m pip install <패키지>

증상: (face)가 떠 있는데 ModuleNotFoundError 원인: 셸의 python이 Homebrew 등 다른 python으로 감(별칭·PATH·stale 셸). 해결: 새 터미널에서 conda activate face, 또는 절대경로 ~/miniconda3/envs/face/bin/python로 실행.

증상: 설치 후 opencv-python is installed/numpy 버전 경고 원인: deepface·insightface·ultralytics 등이 의존성으로 opencv-python·numpy를 끌어옴. conda opencv와 중복. 해결: 확인 후 pip 중복 제거(PART 01 Ch04).

pip list | grep -i opencvpip uninstall -y opencv-python opencv-contrib-python

그 외

증상: facenet-pytorch 설치 후 torch·numpy가 내려감 원인: facenet-pytorch가 torch<2.3·numpy<2를 강제(다운그레이드). 런타임은 정상(PART 04). 해결: numpy2가 꼭 필요하면 facenet-pytorch를 별도 환경으로.

증상: 여러 프레임워크를 한 스크립트에서 쓰니 종료 시 죽음(세그폴트) 원인: TensorFlow+PyTorch+MediaPipe 동시 로드 충돌(macOS). 해결: 검출기·모델별로 서브프로세스를 나눠 격리 실행(PART 02 비교 패널이 이 방식).

증상: mediapipe 옛 예제(mp.solutions.*)가 동작 안 함 원인: 레거시 Solutions가 최신 버전에서 제거. 해결: Tasks API 사용(PART 02·03). 파이썬은 3.8~3.12.

이 장에서 기억할 것

대부분의 설치 문제는 몇 가지 뿌리에서 옵니다. 빌드 까다로운 패키지는 conda-forge로, OpenCV는 4.x 고정, dlib은 20 이상, TF 계열은 tf-keras, 환경은 "그 env의 python으로 직접" 설치. 막히면 증상 메시지를 그대로 검색하고, 이 장과 본편의 해당 PART를 함께 보세요. 가장 흔한 실수는 "활성화됐다고 믿었는데 다른 python으로 실행"하는 것입니다.