sys-hack

파이썬(Python)으로 깃허브(GitHub)의 오픈소스 프로젝트를 클론(Clone)하거나, 웹 크롤링 스크립트를 작성하여 처음 실행할 때 가장 빈번하게 마주하는 에러가 있습니다. 바로 “ModuleNotFoundError: No module named ‘…’” 오류입니다.

예를 들어, 웹 데이터를 수집하려고 코드 상단에 import requests를 적어두고 스크립트를 실행했는데, 파이썬이 “requests라는 모듈을 찾을 수 없다”며 실행을 멈추는 식입니다. 터미널 창에 pip install requests를 분명히 쳤는데도 말이죠. 이 글에서는 에러가 발생하는 구체적인 원인과 실무에서 자주 겪는 사례, 그리고 이를 3분 안에 해결할 수 있는 단계별 가이드를 소개합니다.

1. 에러 발생 원인: 설치한 책을 엉뚱한 책장에 꽂아둔 상황

파이썬 인터프리터는 코드를 실행할 때 필요한 라이브러리(모듈)를 시스템 내의 특정 경로(sys.path)에서 순서대로 검색합니다. 에러가 발생하는 가장 큰 이유는 모듈을 설치한 경로와 파이썬이 실행되면서 모듈을 찾는 경로가 일치하지 않기 때문입니다.

쉽게 비유하자면, A라는 책장에 책을 사서 꽂아두고, B라는 책장에 가서 책을 찾는 것과 같습니다. 구체적인 실무 발생 사례는 다음과 같습니다.

• 사례 A (단순 미설치): 남의 코드를 복사해 왔는데, 내 컴퓨터에는 해당 패키지가 설치되어 있지 않은 경우.
• 사례 B (버전 꼬임): 내 컴퓨터에 Python 3.9와 Python 3.11이 동시에 깔려 있을 때, pip install pandas는 3.9 버전에 설치해 놓고, 정작 코드 실행은 python3.11 script.py로 실행한 경우.
• 사례 C (가상환경 미활성화): 프로젝트 폴더 안에 venv 가상환경을 만들어 패키지를 설치해 놓고, 터미널을 새로 열었을 때 가상환경을 켜지(Activate) 않은 채로 코드를 돌린 경우.

2. 실전 문제 해결 가이드

본인의 상황이 위 사례 중 어디에 해당하는지 파악했다면, 아래의 해결 방법을 순서대로 적용해 보세요.

1단계: 패키지 실제 설치 여부 확인 (사례 A 해결)

가장 먼저 할 일은 오류가 난 모듈이 내 컴퓨터 어딘가에 설치되기는 했는지 확인하는 것입니다. pandas 모듈에서 에러가 났다고 가정하고 아래 명령어를 터미널에 입력합니다.

pip list | grep pandas

아무런 결과가 나오지 않는다면 정말 설치가 안 된 것이므로, pip install pandas 명령어로 설치를 진행하면 즉시 해결됩니다.

2단계: 파이썬 실행 모듈을 통한 안전한 설치 (사례 B 해결)

설치는 되어 있는데 코드를 돌릴 때만 에러가 난다면 파이썬 버전이 꼬인 것입니다. 이럴 때는 단순히 pip install을 쓰지 말고, 코드를 실행할 파이썬 버전을 직접 지목해서 그 안에 패키지를 설치하는 방식(python -m pip)을 써야 합니다.

# 현재 쉘에서 기본으로 잡히는 파이썬 버전에 정확히 설치
python3 -m pip install pandas
# 만약 파이썬 3.10 버전으로 코드를 돌릴 예정이라면 특정 버전 지목
python3.10 -m pip install pandas

실무에서는 경로 꼬임을 방지하기 위해 일반 pip 명령어보다 위 방식을 훨씬 권장합니다.

3단계: 가상 환경(Virtual Environment) 활성화 (사례 C 해결)

가상환경은 프로젝트마다 독립적인 책장을 만들어주는 기능입니다. 가상환경 안에 패키지를 설치했다면, 코드를 실행하기 전에 반드시 터미널에서 해당 가상환경을 ‘활성화(Activate)’ 해야 합니다.

# macOS 및 리눅스(Linux) 환경
source venv/bin/activate
# 윈도우(Windows) 환경
call venv\Scripts\activate

정상적으로 활성화되면 터미널 입력창 맨 앞에 (venv)라는 표시가 생깁니다. 이 상태에서 파이썬 스크립트를 실행하면 모듈을 정확하게 찾아냅니다.

3. 요약 및 주의사항

핵심 요약: ModuleNotFoundError가 발생하면 당황하지 말고 ① 설치 여부를 pip list로 확인하고, ② 실행하는 파이썬 버전에 맞게 python -m pip install로 재설치하며, ③ 가상환경을 사용 중인지 점검하세요.

⚠️ 주의사항: 아나콘다(Anaconda)를 사용하는 데이터 분석 환경의 경우, pip 명령어 대신 가급적 conda install 모듈명을 사용해야 패키지 의존성 충돌(Dependency Clash)을 예방할 수 있습니다.

마치며

오늘은 파이썬 개발 환경을 구축할 때 누구나 한 번쯤 겪는 모듈 인식 에러에 대해 알아보았습니다. 개념만 명확히 잡으면 앞으로 파이썬 환경이 꼬일 일은 확연히 줄어들 것입니다.