Python 가상환경 에러 & 해결 가이드

2026년 4월 8일·9 min read

개발 python venv virtual-environment troubleshooting

Python 스크립트를 처음 실행할 때 마주치는 에러들은 대부분 하나의 원인에서 출발한다. "어느 Python이 실행되고 있는가?"

퍼블리싱 파이프라인 v5를 돌리면서 환경 에러 네 가지를 연달아 만났다. 각각 원인이 달라 보였지만, 결국 가상환경 개념 하나로 연결됐다. 그 과정을 정리한다.

빠른 참조표

에러	원인	해결	핵심 개념
`ModuleNotFoundError: No module named 'requests'`	패키지 미설치	가상환경에서 `pip install`	Python 격리
`externally-managed-environment`	시스템 Python 보호	가상환경 생성	보안 정책
`error: unrecognized arguments: --v5`	잘못된 인자 전달	스크립트 `--help` 확인	함수 시그니처
`no such file or directory: /path/bin/activate`	가상환경 없음	먼저 venv 생성	순서 의존성

1. ModuleNotFoundError: No module named 'requests'

현상

❌ python3 script.py
Traceback (most recent call last):
  File "...", line 20, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

원인

Python이 requests 패키지를 찾지 못한 것이다. 현재 실행 중인 Python에 패키지가 설치되어 있지 않다.

핵심 개념: "어느 Python인가?"

Python은 시스템에 여러 개가 동시에 존재할 수 있다.

시스템 Python (macOS 기본)
  └─ 설치 위치: /usr/bin/python3
  └─ 패키지: Python 필수 패키지만 (외부 패키지 금지)
 
가상환경 Python (프로젝트별 격리)
  └─ 설치 위치: ~/.claude/publish-env/bin/python
  └─ 패키지: 자유롭게 설치 가능

어느 Python을 실행하느냐에 따라 사용 가능한 패키지가 달라진다.

확인 방법

# 현재 어느 Python을 쓰고 있나?
which python3
 
# 가상환경이 활성화되었나?
echo $VIRTUAL_ENV  # 경로 출력되면 OK, 빈 줄이면 미활성화

해결 방법

Step 1: 가상환경 활성화

source ~/.claude/publish-env/bin/activate
# 또는 ~/.zshrc에 자동추가됨 (새 터미널 열면 자동)

Step 2: 패키지 설치

pip install requests
# or
pip install -r requirements.txt

Step 3: 스크립트 실행

python3 script.py

2. externally-managed-environment

현상

❌ pip install requests
error: externally-managed-environment
 
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install xyz
    If you wish to install a library, use a virtual environment

원인

시스템 Python에 외부 패키지를 설치하려 했기 때문이다. macOS는 자신의 Python을 외부 패키지로부터 보호하는 정책을 적용한다.

핵심 개념: 보안 정책

macOS 시스템 Python
  ├─ 역할: macOS 내부 기능 제공 (Siri, 자동화 등)
  ├─ 문제: 외부 패키지로 오염되면 시스템 오류 발생 가능
  └─ 따라서: 외부 패키지 설치 금지 ❌
 
→ 해결책: 격리된 환경(가상환경)에서만 설치를 허가한다

해결 방법

가상환경 생성 (한 번만)

python3 -m venv ~/.claude/publish-env

가상환경 활성화 (매 세션)

source ~/.claude/publish-env/bin/activate

~/.zshrc에 자동추가 (선택사항)

echo 'source ~/.claude/publish-env/bin/activate' >> ~/.zshrc

이후로는 새 터미널을 열 때마다 자동 활성화되고, pip install이 정상 작동한다.

3. error: unrecognized arguments

현상

❌ python3 orchestrate_v5.py --file-key "ABC" --v5
usage: orchestrate_v5.py [-h] --file-key FILE_KEY --node-id NODE_ID ...
orchestrate_v5.py: error: unrecognized arguments: --v5

원인

스크립트가 받지 않는 인자를 전달한 것이다. --v5는 이 스크립트에 정의되지 않은 인자다.

핵심 개념: 함수 시그니처

Python 스크립트는 argparse로 받아들이는 인자를 엄격히 정의한다.

# orchestrate_v5.py 내부
parser.add_argument('--file-key', required=True)  # ✅ 허가
parser.add_argument('--node-id', required=True)   # ✅ 허가
# (--v5는 없음)                                    # ❌ 불허가
 
# phase2_deep.py 내부
parser.add_argument('--node-ids', required=True)  # ✅ node-id (X) vs node-ids (O)

각 스크립트마다 받아들이는 인자가 정확히 다르다.

확인 방법

# 스크립트가 받아들이는 인자 확인
python3 orchestrate_v5.py --help
python3 phase2_deep.py --help

예시

# ❌ 잘못된 사용
python3 orchestrate_v5.py --file-key "ABC" --v5
 
# ✅ 올바른 사용 (orchestrate_v5.py)
python3 orchestrate_v5.py --file-key "ABC" --node-id "123:456"
 
# ✅ 올바른 사용 (phase2_deep.py)
python3 phase2_deep.py --file-key "ABC" --node-ids "123:456"
#                                        ↑ node-ids (복수형)

4. no such file or directory: /path/bin/activate

현상

❌ source ~/.zshrc
/Users/taehoon/.zshrc:145: no such file or directory: /Users/taehoon/.publish-env/bin/activate

원인

~/.zshrc에 activate 경로가 먼저 추가되어 있는데, 실제 가상환경 폴더가 아직 존재하지 않는 경우다.

핵심 개념: 순서 의존성

잘못된 순서:
1. ~/.zshrc에 "activate하기" 추가  ← 파일 없음
2. 터미널 시작 → activate 실행 시도  ❌ 파일이 없어서 에러
 
올바른 순서:
1. 가상환경 폴더 생성
2. ~/.zshrc에 activate 명령 추가
3. 터미널 시작 → activate 실행  ✅ 파일 존재

해결 방법

Step 1: 가상환경 생성 (우선)

python3 -m venv ~/.claude/publish-env

Step 2: 오류 제거 (선택사항)

# ~/.zshrc에서 잘못된 줄 삭제
sed -i '' '/\.publish-env/d' ~/.zshrc
 
# 올바른 경로 추가
echo 'source ~/.claude/publish-env/bin/activate' >> ~/.zshrc

Step 3: 활성화

source ~/.zshrc

전체 실행 흐름도

에러들이 발생하는 순서를 도식으로 보면 이렇다.

사용자: python3 orchestrate_v5.py --file-key ABC --node-id 123:456
  ↓
① Python 인터프리터 시작
  └─ VIRTUAL_ENV 환경변수 확인
     ├─ 값이 있으면 → 가상환경 Python (격리됨) ✅
     └─ 빈 줄이면 → 시스템 Python (제한됨) ❌
  ↓
② import requests 실행
  ├─ 시스템 Python: requests 없음 → ModuleNotFoundError ❌
  └─ 가상환경 Python: requests 설치됨 → 성공 ✅
  ↓
③ argparse로 인자 검증
  ├─ --file-key ABC → 허가됨 ✅
  ├─ --node-id 123:456 → 허가됨 ✅
  └─ --v5 → 정의 안 됨 → error ❌
  ↓
④ 스크립트 실행
  └─ Figma API 호출, Phase 실행 등...

설정 완료 확인 체크리스트

python3 -m venv ~/.claude/publish-env 실행 완료
echo 'source ~/.claude/publish-env/bin/activate' >> ~/.zshrc 실행 완료
source ~/.zshrc 실행 후 재로그인
echo $VIRTUAL_ENV 출력 확인 → ~/.claude/publish-env
pip install requests 성공
python3 orchestrate_v5.py --help 실행 확인

참고: 가상환경 위치

~/.claude/publish-env/
  ├── bin/
  │   ├── python       ← 실제 Python 바이너리
  │   ├── pip          ← 패키지 매니저
  │   └── activate     ← 활성화 스크립트
  ├── lib/
  │   └── python3.x/site-packages/  ← 설치된 패키지들
  └── ...

왜 ~/.claude 안에 놨는가? — 설정/프로젝트 관련 항목을 한 곳에 관리하기 위해서다.

장점:

백업/이동 시 같은 폴더로 관리 가능
프로젝트별로 격리 가능

다음: v5 퍼블리싱 파이프라인 실행

가상환경 설정을 완료한 후 다음처럼 실행한다.

source ~/.zshrc  # 새 터미널이면 필요 없음 (자동 활성화)
python3 ~/.claude/skills/publish-v5/scripts/orchestrate_v5.py \
  --file-key "YOUR_FILE_KEY" \
  --node-id "YOUR_NODE_ID"