NumPy 2.0.0 업데이트 후 발생하는 OpenCV/imutils import 에러 해결 방법
Problem
Python 환경에서 Flask 웹 애플리케이션이나 영상 처리 스크립트를 개발할 때, cv2 (OpenCV)나 imutils 라이브러리를 임포트하는 과정에서 갑작스러운 크래시가 발생할 수 있습니다. 주로 AttributeError: _ARRAY_API not found 또는 ImportError: numpy.core.multiarray failed to import와 같은 에러 메시지가 출력됩니다. 에러 로그를 자세히 살펴보면 “A module that was compiled using NumPy 1.x cannot be run in NumPy 2.0.0 as it may crash"라는 경고 문구를 확인할 수 있습니다. 이는 최근 새로운 가상환경을 세팅하거나 패키지를 최신 버전으로 업데이트한 개발자들이 매우 흔하게 겪는 호환성 문제입니다.
Background
이 문제는 NumPy 라이브러리가 1.x 버전에서 2.0.0 버전으로 메이저 업데이트를 진행하면서 발생한 현상입니다. NumPy는 파이썬 데이터 과학 및 머신러닝 생태계의 기반이 되는 라이브러리로, OpenCV나 Pandas 같은 수많은 서드파티 라이브러리들이 NumPy의 C API에 의존하여 컴파일됩니다. NumPy 2.0.0은 성능 향상과 구조 개선을 위해 기존 1.x 버전과의 C API 및 ABI(Application Binary Interface) 하위 호환성을 일부 포기하는 파괴적 변경(Breaking Changes)을 포함했습니다. 따라서 NumPy 1.x 환경에서 빌드된 기존의 cv2나 imutils 바이너리 파일들은 NumPy 2.0.0 환경에서 정상적으로 메모리를 참조하지 못하고 충돌을 일으키게 됩니다. pip install 시 버전을 명시하지 않으면 기본적으로 최신 버전인 2.0.x가 설치되기 때문에 이 문제가 빈번하게 발생합니다.
Solution
이 문제를 해결하는 가장 확실하고 빠른 방법은 시스템에 설치된 NumPy 2.0.x 버전을 삭제하고, 기존 라이브러리들과 호환되는 1.x 버전으로 다운그레이드하는 것입니다.
방법 1: 특정 안정화 버전(1.26.4)으로 고정하여 설치하기
가장 널리 사용되고 검증된 NumPy 1.x의 마지막 안정화 버전인 1.26.4를 명시적으로 설치하는 방법입니다.
# 기존에 설치된 문제가 되는 numpy 2.0.x 버전을 삭제합니다.
pip uninstall numpy
# 호환성이 검증된 1.26.4 버전을 명시하여 설치합니다.
pip install numpy==1.26.4
방법 2: 2.0 미만의 최신 버전으로 설치하기 (권장)
1.x 버전 대의 최신 보안 패치나 버그 수정본을 자동으로 반영하고 싶다면, 버전 제약 조건을 사용하여 설치하는 것이 좋습니다.
# 기존 numpy 삭제
pip uninstall numpy
# 2.0.0 미만의 버전 중 가장 최신 버전을 자동으로 찾아 설치합니다.
# 따옴표("")를 사용하여 쉘에서 부등호가 리다이렉션으로 인식되지 않도록 합니다.
pip install "numpy<2.0"
방법 3: 의존성 패키지(OpenCV 등) 업데이트 시도
만약 프로젝트에서 반드시 NumPy 2.0.0 이상을 사용해야 한다면, 에러를 발생시키는 패키지(예: opencv-python)가 NumPy 2.0을 지원하도록 다시 빌드된 최신 버전이 나왔는지 확인하고 업그레이드해야 합니다.
# OpenCV 패키지를 최신 버전으로 업그레이드 해봅니다.
pip install --upgrade opencv-python
참고: 이 방법은 해당 라이브러리의 메인테이너가 NumPy 2.0 호환 버전을 릴리즈했을 때만 유효합니다. imutils와 같이 업데이트가 오랫동안 중단된 라이브러리의 경우 방법 1이나 2를 사용해야 합니다.
Deep Dive
프로덕션 환경에서 이러한 갑작스러운 의존성 충돌을 예방하려면 requirements.txt나 Pipfile, pyproject.toml 등에 핵심 라이브러리의 버전을 명확히 고정(Pinning)하는 것이 필수적입니다. 예를 들어 requirements.txt에 numpy<2.0.0이라고 명시해두면, CI/CD 파이프라인이나 다른 개발자의 환경에서 빌드가 깨지는 것을 막을 수 있습니다. 또한, 만약 본인이 C/C++ 확장을 사용하는 파이썬 패키지를 직접 개발하고 있다면, pybind11>=2.12 버전을 사용하여 NumPy 2.0 헤더를 포함해 다시 컴파일해야 NumPy 1.x와 2.x 모두에서 동작하는 모듈을 배포할 수 있습니다.
Conclusion
OpenCV나 imutils 사용 시 발생하는 _ARRAY_API not found 에러는 NumPy 2.0.0의 메이저 업데이트로 인한 ABI 호환성 파괴가 원인입니다. 일반적인 패키지 사용자라면 pip install "numpy<2.0" 명령어를 통해 NumPy를 1.x 버전으로 다운그레이드하는 것이 가장 빠르고 안전한 해결책입니다. 향후 주요 라이브러리들이 NumPy 2.0 생태계로 완전히 전환될 때까지는 의존성 버전을 신중하게 관리해야 합니다.