Python ModuleNotFoundError 완벽 해결: 가상환경(venv) 격리 아키텍처
[Troubleshooting] Python ModuleNotFoundError 완벽 해결: 가상환경(venv) 격리 아키텍처
"분명히 터미널에서 pip install requests라고 입력해서 'Successfully installed' 메시지까지 확인했는데, 파이썬 코드를 실행하면 ModuleNotFoundError: No module named 'requests' 에러가 뜨면서 프로그램이 죽어버립니다."
데이터 분석이나 백엔드 개발을 위해 파이썬(Python)에 입문한 개발자들이 하루에도 수십 번씩 겪는 절망적인 에러입니다. 패키지를 지웠다 깔아보고 파이썬을 재설치해 보지만 해결되지 않습니다.
이 기이한 현상은 당신이 타이핑을 틀려서가 아닙니다. 파이썬 인터프리터와 패키지 매니저(pip)가 바라보는 '경로(PATH)의 불일치' 때문입니다. 본 가이드에서는 OS 전역에 패키지를 쏟아붓는 더러운 관행을 끊어내고, 프로젝트마다 완벽하게 무균실을 구축하는 가상환경(Virtual Environment) 아키텍처를 단호하게 제시합니다.
📌 이 글의 핵심 포인트
- 경로 불일치: 파이썬 2.x와 3.x, OS 기본 파이썬과 Homebrew 파이썬이 얽혀 발생하는 패키지 인식 불가 현상
- 무균실 아키텍처:
python -m venv를 활용한 프로젝트 단위의 완벽한 의존성 격리 공간 구축- 의존성 동결:
requirements.txt를 통한 팀원 간 개발 환경 100% 일치 자동화
1단계: 핵심 원인 분석 - 누구의 pip 인가?
맥(Mac)이나 리눅스(Linux) 시스템에는 OS가 내부적으로 사용하기 위해 설치해 둔 시스템 파이썬이 존재합니다. 당신이 무작정 pip install을 치면, 이 패키지는 '시스템 파이썬'의 라이브러리 폴더로 들어가 버릴 확률이 높습니다.
그런데 막상 당신이 VSCode나 Pycharm에서 실행 버튼을 누르면, 에디터는 당신이 새로 설치한 최신 버전의 '사용자 파이썬(python3)'을 사용해 코드를 실행합니다. 주머니는 A인데, B 주머니를 뒤지며 패키지를 찾고 있으니 당연히 모듈을 찾을 수 없다는 에러(ModuleNotFoundError)가 발생하는 것입니다.
2단계: 완벽한 트러블슈팅 - venv 가상환경 구축
진정한 엔지니어는 절대 OS 전역(Global) 환경에 패키지를 설치하지 않습니다. 프로젝트 폴더 내부에 오직 이 프로젝트만을 위한 파이썬 실행 파일과 패키지 폴더를 따로 구축해야 합니다.
# 1. 프로젝트 폴더로 이동
cd my-python-project
# 2. 'venv'라는 이름의 완벽히 격리된 가상환경 무균실 생성
python3 -m venv venv
# 3. 가상환경 활성화 (Activate) - 이 순간부터 글로벌 파이썬과는 단절됨
# Mac/Linux 환경:
source venv/bin/activate
# Windows 환경:
.\venv\Scripts\activate
# 4. 프롬프트 앞에 (venv)가 뜬 것을 확인 후 패키지 설치
# 이제 설치되는 모든 패키지는 시스템이 아닌 현재 폴더(venv) 내부에만 저장됨
pip install requests
3단계: 팀 협업 아키텍처 - requirements.txt 동결
가상환경을 만들었다면 깃허브(GitHub)에 코드를 올릴 때 venv 폴더 자체를 통째로 올려서는 안 됩니다(용량도 크고 OS마다 실행 파일이 다름). 대신 현재 가상환경에 설치된 패키지들의 '설계도'만 뽑아서 공유해야 합니다.
# 현재 가상환경에 설치된 모든 패키지와 버전을 텍스트 파일로 동결(Freeze)
pip freeze > requirements.txt
# (다른 컴퓨터나 서버에서 코드를 다운로드한 뒤)
# 텍스트 파일을 읽어와 똑같은 버전으로 한 방에 설치
pip install -r requirements.txt
🙋♂️ 자주 묻는 질문 (FAQ)
Q. 가상환경을 켰는데도 VSCode에서 모듈을 못 찾겠다고 노란 줄이 뜹니다.
A. 터미널의 가상환경은 켜졌지만, VSCode 에디터 자체는 아직 글로벌 파이썬을 바라보고 있기 때문입니다. Ctrl + Shift + P (또는 Cmd + Shift + P)를 누르고 Python: Select Interpreter를 검색한 뒤, 프로젝트 폴더 안의 ./venv/bin/python 경로를 수동으로 지정해 주면 완벽하게 해결됩니다.
💡 핵심 정리 및 마무리
파이썬의 의존성 관리는 방치하면 프로젝트 전체를 무너뜨리는 폭탄이 됩니다. 코드를 짜는 것보다 더 중요한 것은 코드가 실행되는 환경(Environment)을 통제하는 것입니다. venv를 통한 의존성 격리를 습관화하여, 내 컴퓨터뿐만 아니라 그 어떤 서버에서도 100% 동일하게 동작하는 무결점 파이썬 파이프라인을 구축하십시오.
댓글
댓글 쓰기