윈도우에서 파이썬 가상환경(venv) 설정 총정리

업무 자동화 스크립트를 하나 더 만들려고 pip install을 돌렸더니, 멀쩡히 돌아가던 예전 스크립트가 갑자기 에러를 뱉습니다. 새 패키지가 요구한 라이브러리 버전이 기존 것을 덮어썼기 때문입니다. 이걸 되돌리느라 반나절을 날리는 일이 드물지 않은데, 원인도 해결책도 하나입니다. 파이썬 가상환경 설정을 안 한 채 전역에 계속 설치했기 때문입니다. 이 글에서는 윈도우 기준으로 venv를 만드는 법부터, 윈도우에서만 유독 자주 터지는 활성화 오류와 그 해결법까지 한 번에 정리합니다.

전역 설치가 왜 문제가 되나

가상환경 없이 pip install을 하면 패키지가 파이썬 설치 폴더 한 곳에 쌓입니다. 프로젝트가 하나일 때는 아무 문제가 없습니다. 문제는 두 번째 프로젝트부터입니다.

A 스크립트는 requests 2.28에서 검증했는데, B를 설치하다가 requests 2.32로 올라가 A가 깨집니다.
어떤 패키지가 어떤 스크립트에 필요한지 구분이 안 돼서, 지워도 되는지 판단할 수 없습니다.
다른 PC에 옮길 때 “무엇을 깔아야 하는지” 목록이 없어 처음부터 다시 헤맵니다.

가상환경은 프로젝트 폴더 안에 파이썬과 패키지를 통째로 격리해 둡니다. A 폴더에서 무엇을 설치하든 B 폴더에는 영향이 없고, 망가지면 폴더만 지우고 다시 만들면 됩니다.

venv로 가상환경 만들기

파이썬 3.3부터 venv가 기본 내장이라 따로 설치할 게 없습니다. 명령 세 줄이면 끝납니다.

# 1. 프로젝트 폴더로 이동
cd C:\work\my-project

# 2. .venv 라는 이름으로 가상환경 생성
python -m venv .venv

# 3. 활성화 (PowerShell)
.venv\Scripts\Activate.ps1

# 3-1. 활성화 (명령 프롬프트 cmd)
.venv\Scripts\activate.bat

프롬프트 맨 앞에 (.venv)가 붙으면 활성화된 상태입니다. 이때부터 pip install은 전부 그 폴더 안으로만 들어갑니다. 빠져나올 때는 deactivate를 입력하면 됩니다.

폴더 이름을 .venv로 쓰는 이유는 관례입니다. VS Code를 비롯한 대부분의 도구가 이 이름을 자동으로 찾아 인식합니다.

가장 흔한 오류: PowerShell 실행 정책

윈도우에서 venv를 처음 쓰는 사람 열에 아홉이 여기서 막힙니다. 활성화 명령을 넣었는데 “이 시스템에서 스크립트를 실행할 수 없으므로”라는 빨간 메시지가 뜨는 경우입니다. 파이썬이나 venv 문제가 아니라, PowerShell이 기본적으로 스크립트 실행을 막아둔 탓입니다.

# 오류 메시지
# .venv\Scripts\Activate.ps1 파일을 로드할 수 없습니다.
# 이 시스템에서 스크립트를 실행할 수 없으므로 ...

# 현재 사용자 범위에만 서명된 원격 스크립트 실행을 허용
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 적용됐는지 확인
Get-ExecutionPolicy -List

PowerShell 실행 정책 오류와 해결 실제 화면 — 실행 정책을 Restricted로 두고 실제로 재현한 오류입니다. CurrentUser 범위만 RemoteSigned로 바꾸면 풀립니다.

-Scope CurrentUser를 붙이면 관리자 권한 없이 현재 계정에만 적용되므로 시스템 전체 보안 설정은 그대로입니다. 회사 PC라 정책 변경이 막혀 있다면, PowerShell 대신 명령 프롬프트(cmd)를 열고 .venv\Scripts\activate.bat을 쓰면 실행 정책과 무관하게 동작합니다.

python 명령을 못 찾을 때

“python은(는) 내부 또는 외부 명령… 이 아닙니다”가 뜨거나, 엉뚱하게 마이크로소프트 스토어가 열린다면 PATH 등록이 안 됐거나 윈도우의 앱 실행 별칭이 가로챈 경우입니다. 이럴 때는 파이썬 설치 시 함께 깔리는 런처 py를 쓰면 대부분 그냥 해결됩니다.

# 설치된 파이썬 버전 전체 확인
py --list

# 3.11 로 가상환경 만들기
py -3.11 -m venv .venv

# 가상환경 안에서 실제로 어떤 파이썬이 잡혔는지 확인
.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"

py 런처는 버전을 골라 실행할 수 있어서, 프로젝트마다 파이썬 버전이 다를 때 특히 편합니다. 스토어 별칭이 계속 걸리적거리면 설정 → 앱 → 고급 앱 설정 → 앱 실행 별칭에서 python 항목을 꺼두세요.

requirements.txt로 환경 그대로 옮기기

가상환경을 만들었다면 반드시 같이 챙겨야 할 게 패키지 목록입니다. 이 파일 하나가 있으면 새 PC에서도 같은 환경을 몇 분 만에 복원할 수 있습니다.

# 지금 환경에 깔린 패키지를 파일로 고정
pip freeze > requirements.txt

# 다른 PC / 다른 사람이 그대로 재현
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

pip freeze로 만든 requirements.txt 실제 내용 — requests 하나만 설치했는데 의존 패키지까지 5줄이 적힙니다. 옮긴 PC에서 이대로 복원됩니다.

가상환경 폴더 자체는 절대 깃에 올리지 않습니다. 용량이 수백 MB로 크고, 어차피 다른 PC에서는 그대로 못 쓰기 때문입니다. 올려야 할 건 requirements.txt 하나입니다.

# .gitignore
.venv/
__pycache__/
*.pyc

VS Code에서 가상환경 인식시키기

터미널에서는 잘 되는데 VS Code에서 실행하면 ModuleNotFoundError가 나는 경우가 있습니다. 편집기가 아직 전역 파이썬을 보고 있어서입니다.

Ctrl + Shift + P로 명령 팔레트를 엽니다.
Python: Select Interpreter를 선택합니다.
목록에서 경로에 .venv가 들어간 항목을 고릅니다.
열려 있던 터미널은 닫고 새로 엽니다. 기존 터미널에는 반영되지 않습니다.

제대로 잡혔다면 VS Code 창 아래쪽 상태 표시줄에 .venv가 표시됩니다. 그래도 안 되면 python -c "import sys; print(sys.executable)"로 실제 실행 경로를 찍어 확인하는 게 가장 빠릅니다.

venv 말고 다른 선택지

venv 하나로 대부분 충분하지만, 상황에 따라 더 나은 도구가 있습니다.

도구	설치	적합한 상황	특징
venv	파이썬에 내장	대부분의 개인 프로젝트	추가 설치가 없고 어디서나 동일하게 동작
virtualenv	별도 설치 (pip)	구버전 파이썬을 함께 다룰 때	venv보다 오래됐고 지원 버전 범위가 넓음
conda	Anaconda / Miniconda	데이터 분석·과학 계산	파이썬 외 의존성(컴파일러 등)까지 관리
uv	별도 설치	패키지 설치가 느려 답답할 때	Rust로 작성된 신형 도구, 설치·의존성 해석이 빠름

처음이라면 고민하지 말고 venv로 시작하세요. 넘어가야 할 이유가 생겼을 때 옮겨도 늦지 않습니다.

주의할 점

가상환경 폴더는 복사하거나 이동하면 깨집니다. 내부 설정 파일과 실행 스크립트에 생성 당시의 절대 경로가 박히기 때문입니다. 프로젝트 폴더 위치를 옮겼다면 .venv를 지우고 다시 만든 뒤 pip install -r requirements.txt로 복원하세요.

가상환경을 활성화하지 않은 채 pip install을 하면 다시 전역에 설치됩니다. 프롬프트 앞에 (.venv)가 있는지 늘 확인하세요.
경로에 한글이나 공백이 들어가면 일부 패키지 설치가 실패할 수 있습니다. 작업 폴더는 C:\work처럼 짧은 영문 경로를 권합니다.
pip freeze는 의존성으로 딸려온 패키지까지 전부 기록합니다. 목록을 직접 관리하고 싶다면 필요한 패키지만 손으로 적은 별도 파일을 두는 편이 낫습니다.
작업 스케줄러에 등록할 때는 python script.py가 아니라 C:\work\my-project\.venv\Scripts\python.exe script.py처럼 가상환경 안의 실행 파일을 전체 경로로 지정해야 합니다.

마무리

지금 쓰고 있는 프로젝트 폴더 하나에서 python -m venv .venv를 한 번 실행해 보는 것으로 충분합니다. 기존 환경은 전혀 건드리지 않으니 부담 없이 시도할 수 있고, 마음에 안 들면 .venv 폴더만 지우면 원래대로 돌아갑니다. 익숙해지면 새 프로젝트를 만들 때마다 반사적으로 하게 되는 습관이 됩니다.

다음 글에서는 사진 수십 장의 크기를 줄이고 워터마크까지 한 번에 넣는 이미지 일괄 처리 스크립트를 다루겠습니다.