라떼군 이야기

Gensim 사용 시 SciPy 'triu' ImportError 해결 방법 (ImportError: cannot import name 'triu')

Problem

Python 환경에서 자연어 처리 라이브러리인 Gensim을 사용하기 위해 import gensim을 실행했을 때, 프로그램이 중단되며 에러가 발생하는 상황입니다.

주로 최신 환경에서 패키지를 설치한 후 발생하며, 구체적인 에러 메시지는 다음과 같습니다:

ImportError: cannot import name 'triu' from 'scipy.linalg'

이 문제는 Gensim이 내부적으로 의존하고 있는 scipy 라이브러리에서 특정 함수를 찾지 못해 발생합니다.

Background

이 오류의 근본적인 원인은 라이브러리 간의 버전 호환성(Dependency Compatibility) 문제입니다.

1. Gensim의 의존성: Gensim은 행렬 연산 등을 위해 scipy 라이브러리를 사용합니다. 구형 Gensim 코드는 scipy.linalg 모듈에서 triu(상삼각행렬), tril, tri 같은 함수를 가져오도록 작성되어 있습니다.
2. SciPy의 변경 사항: SciPy 1.11.0 버전부터 scipy.linalg 아래의 triu, tril 등의 함수들이 Deprecated(사용 중단 예정) 처리되었습니다. 이후 SciPy 1.13.0 버전에서는 해당 함수들이 완전히 제거되었습니다.

즉, 사용자의 환경에 설치된 SciPy 버전이 1.13.0 이상일 경우, Gensim이 더 이상 존재하지 않는 함수를 호출하려고 시도하기 때문에 ImportError가 발생하는 것입니다.

Solution

가장 확실한 해결 방법은 호환되지 않는 최신 버전의 SciPy를 제거하고, 해당 함수가 존재하는 이전 버전으로 다운그레이드하는 것입니다.

방법 1: SciPy 1.12 버전으로 설치 (권장)

SciPy 1.12 버전은 해당 함수들이 제거되기 직전의 버전이므로, 비교적 최신 기능을 유지하면서 문제를 해결할 수 있습니다.

# 기존 scipy가 있다면 제거되거나 덮어씌워집니다.
pip install scipy==1.12

방법 2: SciPy 1.10.1 버전으로 설치 (안정성 중시)

만약 1.12 버전에서도 문제가 발생하거나 더 보수적인 환경 구성이 필요하다면, 1.10.1 버전을 사용하는 것이 좋습니다.

# 특정 버전을 명시하여 설치
pip install scipy==1.10.1

설치 확인

설치가 완료된 후 Python 인터프리터에서 버전을 확인하고 Gensim을 임포트 해봅니다.

import scipy
import gensim

print(f"SciPy version: {scipy.__version__}")
# 에러 없이 출력된다면 성공입니다.
print("Gensim imported successfully!")

(참고) Poetry나 Conda를 사용하는 경우

Poetry를 사용한다면 pyproject.toml을 수정한 후 업데이트합니다:

poetry add "scipy==1.12"

Conda를 사용한다면:

conda install scipy=1.12

Deep Dive

의존성 관리의 중요성

단순히 패키지 버전을 낮추는 것은 ‘임시 해결책’에 가깝습니다. 만약 프로젝트 내의 다른 라이브러리(예: Scikit-learn 최신 버전 등)가 SciPy 1.13 이상의 기능을 필수적으로 요구한다면, SciPy를 다운그레이드했을 때 다른 곳에서 에러가 터질 수 있습니다.

해결을 위한 Best Practice

1. 가상 환경 사용: 프로젝트마다 venv나 conda 환경을 분리하여 라이브러리 충돌을 방지해야 합니다.
2. 버전 고정 (Pinning): requirements.txt 파일에 scipy<1.13과 같이 허용 범위를 명시하여, 의도치 않게 최신 버전이 설치되는 것을 막아야 합니다.
3. 라이브러리 업데이트 확인: 근본적으로는 Gensim 라이브러리가 최신 SciPy에 대응하도록 업데이트되어야 합니다. Gensim의 최신 릴리스 노트를 주기적으로 확인하여 패치 버전이 나왔는지 체크하는 것이 좋습니다.

Conclusion

ImportError: cannot import name 'triu' from 'scipy.linalg' 에러는 SciPy 라이브러리의 버전 업데이트로 인해 특정 함수가 제거되어 발생합니다. 이를 해결하기 위해 SciPy 버전을 1.12 또는 1.10.1로 고정하여 설치하면 즉시 문제를 해결할 수 있습니다. 장기적으로는 프로젝트의 의존성 관리를 철저히 하고 라이브러리 업데이트를 주시하는 것이 중요합니다.

• SciPy 1.11.0 Release Notes (Deprecations)
• Gensim Documentation