[에러 해결] Python ModuleNotFoundError: ‘nubra_sdk’ 모듈을 찾을 수 없는 원인과 해결 방법

파이썬 개발을 하다 보면 분명히 패키지를 설치했는데도 불구하고 ModuleNotFoundError를 만나 당황하는 경우가 종종 있습니다. 특히 pip install 명령이 성공적으로 완료되었고 pip show 명령으로 설치를 확인했음에도 불구하고 스크립트 실행 시 모듈을 찾을 수 없다는 에러가 발생한다면, 그 원인을 파악하기가 더욱 어렵게 느껴질 수 있습니다. 이번 문서에서는 nubra-sdk 설치 후 발생하는 ModuleNotFoundError: No module named 'nubra_sdk' 문제를 예시로 들어, 이러한 유형의 에러가 발생하는 근본적인 원인을 분석하고 명확한 해결 방법을 제시합니다. 개발자분들이 이 에러를 신속하게 해결하고, 향후 개발 과정에서 유사한 문제를 예방할 수 있도록 돕는 것이 목표입니다.

1. 에러 발생 상황

사용자는 nubra-sdk 패키지를 설치하기 위해 다음과 같은 pip 명령을 사용했습니다.

pip install nubra-sdk

이 설치 명령은 성공적으로 완료되었으며, pip show nubra-sdk 명령으로 패키지가 제대로 설치되었음을 확인할 수 있었습니다. 그러나 작성한 파이썬 스크립트의 첫 줄에서 nubra_sdk 모듈을 임포트하는 시점에 다음과 같은 에러가 발생했습니다.

from nubra_sdk import InitNubraSdk
# ModuleNotFoundError: No module named 'nubra_sdk'

분명히 설치는 되었는데, 파이썬 인터프리터는 해당 모듈을 찾지 못하는 모순적인 상황에 직면한 것입니다.

2. 명확한 발생 원인

이러한 ModuleNotFoundError는 대부분 파이썬 환경 불일치에서 비롯됩니다.

2.1. 파이썬 가상 환경(Virtual Environment) 불일치

가장 흔한 원인으로, pip install 명령을 실행한 파이썬 환경과 스크립트를 실행한 파이썬 환경이 다른 경우입니다. 파이썬은 여러 버전을 동시에 설치하거나, 프로젝트별로 독립적인 패키지 의존성을 관리하기 위해 가상 환경(Virtual Environment)을 사용합니다.

• 특정 가상 환경 A에서 pip install nubra-sdk를 실행하여 패키지를 설치했습니다.
• 하지만 사용자가 스크립트를 실행할 때는 가상 환경 A가 활성화되지 않은 상태이거나, 다른 가상 환경 B 또는 시스템 전역 파이썬 환경에서 실행되고 있는 것입니다.

각 파이썬 환경은 자신만의 site-packages 디렉토리를 가지며, pip install은 현재 활성화된(또는 기본) 환경의 site-packages에 패키지를 설치합니다. 따라서 스크립트가 다른 환경에서 실행되면, 해당 환경에서는 nubra_sdk가 설치되어 있지 않으므로 모듈을 찾을 수 없게 됩니다.

2.2. 잘못된 파이썬 인터프리터 사용

시스템에 여러 버전의 파이썬(예: Python 3.8, Python 3.9)이 설치되어 있고, 각 버전에 대응하는 pip가 따로 존재할 수 있습니다. 예를 들어 pip install nubra-sdk는 Python 3.8의 패키지 디렉토리에 설치했지만, 스크립트를 python3.9 your_script.py와 같이 Python 3.9 인터프리터로 실행하는 경우에도 이 에러가 발생할 수 있습니다.

2.3. PYTHONPATH 환경 변수 문제 (드문 경우)

파이썬은 모듈을 찾을 때 sys.path에 정의된 경로들을 순회합니다. 이 경로에는 표준 라이브러리 경로, 가상 환경의 site-packages 경로, 그리고 PYTHONPATH 환경 변수에 지정된 경로 등이 포함됩니다. 만약 어떤 이유로 PYTHONPATH가 잘못 설정되어 있거나, 파이썬이 패키지가 설치된 경로를 정상적으로 찾지 못하는 특수한 상황일 수도 있습니다.

3. 해결 방법 및 코드 예시

가장 효과적이고 권장되는 해결책은 올바른 파이썬 가상 환경을 활성화하고 그 안에서 작업을 수행하는 것입니다.

3.1. 추천 해결책: 가상 환경(Virtual Environment) 확인 및 활용

대부분의 ModuleNotFoundError는 가상 환경 불일치로 발생하므로, 현재 스크립트를 실행하려는 파이썬 환경을 명확히 하고, 해당 환경에 패키지가 올바르게 설치되어 있는지 확인하는 것이 중요합니다.

단계 1: 현재 활성화된 파이썬 인터프리터 확인

스크립트를 실행하려는 환경에서 다음 명령을 실행하여 어떤 파이썬 인터프리터가 사용되고 있는지 확인합니다.

# Linux/macOS
which python
python -c "import sys; print(sys.executable)"

# Windows
where python
python -c "import sys; print(sys.executable)"

이 경로가 예상한 가상 환경 내의 파이썬 인터프리터인지 확인하세요. 예를 들어, /Users/youruser/myproject/venv/bin/python과 같아야 합니다.

단계 2: 가상 환경 생성 및 활성화 (권장)

아직 가상 환경을 사용하고 있지 않다면, 지금이라도 생성하고 활성화하는 것이 가장 좋습니다. 프로젝트 디렉토리 내에서 다음을 실행합니다.

# 1. 가상 환경 생성 (venv_name 대신 원하는 이름 사용)
python -m venv venv_name

# 2. 가상 환경 활성화

# Linux/macOS
source venv_name/bin/activate

# Windows (Command Prompt)
venv_name\Scripts\activate

# Windows (PowerShell)
venv_name\Scripts\Activate.ps1

가상 환경이 활성화되면 터미널 프롬프트 앞에 (venv_name)과 같은 표시가 나타납니다.

단계 3: 가상 환경 내에서 패키지 설치

가상 환경이 활성화된 상태에서 nubra-sdk를 다시 설치합니다. 이때 사용되는 pip는 현재 활성화된 가상 환경에 속한 pip입니다.

pip install nubra-sdk

단계 4: 스크립트 실행

이제 가상 환경이 활성화된 상태에서 스크립트를 실행하면, nubra_sdk 모듈을 정상적으로 찾을 수 있을 것입니다.

python your_script.py

3.2. 대체 해결책: 특정 파이썬 인터프리터의 pip 사용 (비권장)

만약 가상 환경을 사용하지 않고 시스템 전역 환경에서 작업해야 한다면, 특정 파이썬 인터프리터에 해당하는 pip를 명시적으로 사용하는 것이 좋습니다.

# 설치하려는 파이썬 버전에 맞는 pip 사용 예시
python3.9 -m pip install nubra-sdk

# 또는 현재 PATH에 있는 'python' 인터프리터에 설치
python -m pip install nubra-sdk

이 방법은 현재 스크립트를 실행할 python 명령이 어떤 인터프리터를 가리키는지 확실할 때 유용합니다. 항상 python -m pip 형태로 pip를 호출하는 습관을 들이면, 어떤 파이썬 인터프리터에 패키지가 설치되는지 명확히 할 수 있어 환경 불일치 문제를 줄일 수 있습니다.

4. 향후 예방을 위한 팁

유사한 ModuleNotFoundError를 다시 겪지 않기 위한 몇 가지 예방 팁입니다.

4.1. 항상 가상 환경 사용

새로운 파이썬 프로젝트를 시작할 때는 항상 가상 환경을 만들고 활성화한 후 작업을 시작하세요. 이는 프로젝트별 의존성 충돌을 방지하고, 특정 프로젝트에 필요한 패키지만 깔끔하게 관리할 수 있도록 돕습니다.

• python -m venv .venv (프로젝트 루트에 .venv 폴더로 가상 환경 생성)
• source .venv/bin/activate (Linux/macOS) 또는 .venv\Scripts\activate (Windows)

4.2. 일관된 명령 사용

pip install 대신 python -m pip install을 사용하고, python 명령으로 스크립트를 실행하는 습관을 들이면, 어떤 파이썬 인터프리터와 pip가 사용되는지 명확히 알 수 있습니다. 특히 IDE(VS Code, PyCharm 등)를 사용하는 경우, 해당 IDE가 올바른 가상 환경의 인터프리터를 사용하도록 설정되어 있는지 확인해야 합니다.

4.3. 의존성 관리 파일 활용

프로젝트의 모든 의존성을 requirements.txt 파일에 기록하세요. 새로운 환경에서 프로젝트를 설정할 때, 가상 환경을 활성화한 후 pip install -r requirements.txt 명령으로 모든 필요한 패키지를 한 번에 설치할 수 있습니다.

# requirements.txt 파일 생성
pip freeze > requirements.txt

# 다른 환경에서 설치
pip install -r requirements.txt

이 문서를 통해 ModuleNotFoundError의 주요 원인인 파이썬 환경 불일치 문제를 명확히 이해하고, 효과적인 해결책을 적용하여 개발 생산성을 높이시길 바랍니다.