Python venv 가상환경 오류: activate·pip 경로·패키지 설치 실패 진단법

venv 오류가 나면 먼저 활성화 명령 자체보다 실행 중인 Python과 pip가 같은 가상환경을 가리키는지 확인하세요. 설치는 항상 python -m pip으로 실행하면, 현재 Python 인터프리터와 연결된 pip를 사용합니다. 활성화는 편의 기능일 뿐 필수는 아니므로, 활성화가 막힌 환경에서는 .venv 내부 Python을 직접 실행할 수 있습니다.

실행 중인 Python부터 확인하기

macOS·Linux에서는 프로젝트 루트에서 다음 명령을 실행합니다.

python3 -m venv .venv
source .venv/bin/activate

python -c 'import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)'
python -m pip --version

sys.executable과 python -m pip --version의 출력 경로에 .venv가 보이면 해당 가상환경의 Python과 pip를 사용 중입니다. sys.prefix != sys.base_prefix이면 현재 인터프리터는 가상환경에서 실행되고 있는 것입니다.

import sys

print(f"Python executable: {sys.executable}")
print(f"sys.prefix: {sys.prefix}")
print(f"sys.base_prefix: {sys.base_prefix}")
print(f"Running in a venv: {sys.prefix != sys.base_prefix}")

디렉터리 경로에 .venv나 activate라는 문자열이 포함됐는지로 가상환경 여부를 판단하면, 환경 이름을 다르게 지은 경우 오판할 수 있습니다.

activate가 실행되지 않을 때

bash와 zsh는 같은 POSIX용 활성화 스크립트를 사용합니다. 따라서 zsh에서 bash 전용 스크립트가 필요하다는 설명은 맞지 않습니다. 다만 fish, csh/tcsh, Windows PowerShell은 각각 전용 스크립트를 호출해야 합니다.

# macOS / Linux: bash, zsh
source .venv/bin/activate

# fish
source .venv/bin/activate.fish

# csh, tcsh
source .venv/bin/activate.csh

# Windows cmd.exe
.venv\Scripts\activate.bat

# Windows PowerShell
.venv\Scripts\Activate.ps1

# POSIX의 PowerShell(pwsh)
.venv/bin/Activate.ps1

POSIX 셸에서 source와 .은 같은 역할을 합니다. 또한 source는 파일을 현재 셸에서 읽어 실행하므로, activate 파일에 chmod +x를 적용하는 것은 일반적인 해결책이 아닙니다.

Windows PowerShell에서 Activate.ps1이 실행 정책으로 차단될 수 있습니다. 조직 정책을 먼저 확인한 뒤, 사용자 범위 설정이 허용되는 환경이라면 다음 명령을 검토할 수 있습니다.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Python 공식 문서도 PowerShell 활성화 스크립트 실행에 이 설정이 필요할 수 있다고 안내합니다.

활성화 없이 가상환경 사용하기

활성화는 가상환경의 실행 파일 경로를 현재 셸의 PATH 앞에 추가하는 작업입니다. 따라서 활성화가 실패했거나 CI처럼 셸 상태에 의존하고 싶지 않은 경우, 가상환경 내부 Python을 직접 호출하면 됩니다.

# macOS / Linux
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check

# Windows PowerShell
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip check

프로젝트가 pytest를 의존성으로 설치한다면 같은 방식으로 테스트도 실행할 수 있습니다.

.venv/bin/python -m pytest

설치했는데 ModuleNotFoundError가 날 때

다음 명령은 셸의 PATH에 따라 시스템 Python용 pip나 다른 가상환경의 pip를 선택할 수 있습니다.

pip install -r requirements.txt

대신 실행할 Python을 앞에 붙여 설치 대상 환경을 고정합니다.

python -m pip install -r requirements.txt
python -m pip --version

python -m pip은 지정한 python 인터프리터로 pip를 실행합니다. 그러므로 활성화하지 않은 상태에서도 아래 명령은 .venv에 설치합니다.

.venv/bin/python -m pip install 패키지이름

command -v python, command -v pip으로 셸이 찾는 실행 파일 경로를 함께 볼 수 있지만, 실제 설치 대상 확인에는 python -m pip --version이 더 직접적입니다.

command -v python
command -v pip
python -m pip --version

venv 생성이나 pip 준비가 실패할 때

기본적으로 python -m venv .venv는 가상환경 안에 pip를 부트스트랩합니다. --without-pip으로 만들었다면 pip는 생성되지 않습니다. No module named venv처럼 생성 단계에서 실패한다면, 일부 운영체제 배포판에서는 venv 기능이 별도 Python 패키지로 제공될 수 있으므로 현재 배포판의 Python 패키지 구성을 확인해야 합니다.

이미 만든 환경이 의심되면 프로젝트 코드가 아닌 가상환경 디렉터리만 삭제한 뒤 새로 만듭니다.

rm -rf .venv
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check

rm -rf .venv는 대상 디렉터리를 영구 삭제합니다. 실행 전 현재 위치가 프로젝트 루트인지와 삭제 대상이 정확히 .venv인지 확인해야 합니다.

가상환경은 복사하거나 이동해 재사용하는 대상이 아니라 새 위치에서 재생성하는 대상으로 다루는 편이 안전합니다. 설치된 스크립트가 가상환경 내부 Python의 절대 경로를 가리킬 수 있기 때문입니다. 프로젝트 경로를 옮긴 뒤 실행이 실패했다면 기존 .venv를 삭제하고 새 경로에서 다시 생성하세요.

requirements.txt 설치가 실패할 때

pip install -r requirements.txt 실패는 가상환경 오류가 아니라 특정 패키지의 설치 조건 문제일 수 있습니다. wheel이 없는 패키지는 소스 배포본에서 빌드될 수 있으며, 현재 Python 버전과 운영체제에 맞는 컴파일러, 헤더, 외부 라이브러리가 필요할 수 있습니다.

우선 실패한 패키지명과 현재 Python 버전을 확인하고, 자세한 설치 로그를 봅니다.

.venv/bin/python --version
.venv/bin/python -m pip install -r requirements.txt -v

--no-binary는 wheel을 사용하지 않고 소스 패키지를 사용하도록 강제합니다. 일반적인 설치 실패 해결책으로 쓰면 오히려 컴파일 요구 사항 때문에 실패할 수 있습니다. 반대로 --only-binary는 wheel이 없는 패키지를 설치하지 못하게 합니다. 두 옵션은 원인 진단이나 배포 정책에 따라 제한적으로 사용해야 합니다.

설치가 끝난 뒤 의존성 관계가 깨졌는지 확인하려면 다음 명령을 실행합니다.

.venv/bin/python -m pip check

pip check는 현재 설치된 패키지 사이의 의존성 충돌을 검사합니다. 배포 재현성이 중요한 프로젝트라면 테스트를 통과한 의존성 버전을 고정하고, 필요할 때 --require-hashes로 요구 사항 파일의 해시 검증을 적용할 수 있습니다.

시스템 Python 설치가 차단될 때

Linux 배포판이나 OS 패키지 관리자가 제공한 Python은 외부 관리 환경으로 표시될 수 있습니다. 이 경우 pip는 시스템 전역 Python의 패키지 설치·삭제를 막고 가상환경 사용을 유도합니다. 시스템 환경을 우회하기보다 프로젝트별 .venv를 만든 뒤 그 안에 설치하세요.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

--break-system-packages는 외부 관리 Python의 설치 제한을 우회하도록 허용하는 옵션입니다. 프로젝트 의존성을 설치하기 위해 습관적으로 사용하면 OS 패키지 관리자와 충돌할 수 있으므로, 일반적인 개발·배포 해결책으로는 적합하지 않습니다.

가상환경 디렉터리는 Git에 커밋하지 않고, 배포 환경에서 새로 생성하는 편이 좋습니다. 프로젝트 루트의 .gitignore에는 다음처럼 추가할 수 있습니다.

.venv/

CI에서도 source activate에 의존하지 말고 가상환경 내부 Python을 직접 호출하면, 셸 종류와 PATH 상태 때문에 다른 Python이나 pip가 선택되는 문제를 줄일 수 있습니다.

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check

사설 패키지 인덱스를 함께 사용한다면 --extra-index-url을 무심코 추가하지 않아야 합니다. pip는 공개 인덱스와 추가 인덱스를 함께 검색할 때 의존성 혼동 문제가 생길 수 있다고 경고합니다.