파이썬 가상환경 venv 만들기: 활성화·패키지 설치·삭제까지

파이썬 가상환경은 프로젝트 폴더의 터미널에서 python -m venv .venv를 실행하면 만들어집니다(python 대신 Windows는 py, macOS·Linux는 python3를 씁니다). 활성화는 PowerShell에서 .venv\Scripts\Activate.ps1, 명령 프롬프트에서 .venv\Scripts\activate.bat, macOS·Linux에서 source .venv/bin/activate입니다. 활성화한 뒤에는 pip install이 그 프로젝트의 .venv 폴더에만 패키지를 설치하고, 삭제는 deactivate 후 폴더를 지우면 끝입니다.

파이썬 가상환경이 필요한 이유

가상환경 없이 pip를 쓰면 같은 파이썬을 쓰는 모든 프로젝트가 site-packages 폴더 하나를 함께 씁니다. 프로젝트 A는 예전 pandas로, 프로젝트 B는 더 새로운 버전으로 만들었다면 두 버전은 한 폴더에 공존할 수 없고, B를 위해 업그레이드하는 순간 A가 조용히 망가질 수 있습니다. 가상환경은 프로젝트마다 전용 패키지 폴더를 주어 이 충돌을 막습니다.

venv 모듈은 파이썬 3.3부터 표준 라이브러리에 포함되어 따로 설치할 필요가 없습니다. 가상환경은 이미 설치된 "기본(base)" 파이썬 위에 만들어지고, 기본적으로 그 파이썬의 패키지와는 분리됩니다. 공식 문서가 밝힌 특징 세 가지를 기억해 두세요.

• 버려도 되는 폴더: 지우고 다시 만들기 쉬워야 하니 내 코드를 그 안에 두지 않습니다.
• Git 제외 대상: 환경 자체 대신 패키지 목록 파일을 커밋합니다.
• 복사·이동 불가: 옮기지 않고 새 위치에서 다시 만듭니다.

venv 만들기: 가상환경 생성 방법

1. 터미널을 열고 프로젝트 폴더로 이동합니다.
2. 운영체제에 맞는 명령을 실행합니다. Windows는 py -m venv .venv, macOS·Linux는 python3 -m venv .venv입니다. 마지막 인자가 폴더 이름이며, .venv는 Python Packaging User Guide가 쓰는 이름입니다.
3. 몇 초 기다리면 폴더가 만들어지고 pip도 함께 설치됩니다(--without-pip를 붙이지 않는 한 기본 동작).

.venv 안에는 pyvenv.cfg(home 항목이 만든 파이썬을 가리킴), python·pip·활성화 스크립트가 든 Scripts(macOS·Linux는 bin), 패키지가 쌓이는 Lib\site-packages(macOS·Linux는 lib/pythonX.Y/site-packages)가 있습니다. 파이썬 3.13부터는 .gitignore도 환경 폴더 안에 기본으로 생겨서 Git이 자동으로 건너뜁니다.

venv 활성화 방법: Windows·macOS·Linux

활성화(activate)하면 가상환경의 Scripts(또는 bin) 폴더가 PATH 맨 앞에 놓여서, python이나 pip를 입력하면 .venv 안의 것이 실행됩니다.

성공하면 프롬프트 앞에 보통 (.venv)가 붙습니다. 확인하려면 PowerShell은 Get-Command python, 명령 프롬프트는 where python, macOS·Linux는 which python을 실행해 첫 번째 경로가 .venv 안쪽인지 보세요. PowerShell의 where는 다른 명령(Where-Object)의 별칭이라 쓸 만한 답이 나오지 않습니다.

활성화는 필수가 아닙니다. .venv\Scripts\python app.py나 .venv/bin/python app.py처럼 가상환경의 인터프리터를 직접 실행해도 됩니다. 다만 활성화는 열린 터미널 창에만 적용되므로 새 창에서는 다시 해야 합니다.

패키지 설치와 requirements.txt 저장

활성화한 상태에서 평소처럼 설치합니다. pip 대신 python -m pip로 실행하면 python이 가리키는 바로 그 인터프리터의 pip가 쓰입니다.

python -m pip install requests
python -m pip freeze > requirements.txt

pip freeze는 설치된 패키지를 이름==버전 줄로 고정해 출력하며, pip install이 다시 읽는 형식 그대로입니다. 공식 파이썬 튜토리얼도 이를 requirements.txt로 저장하는 것을 흔한 관례로 소개합니다. requests 하나만 설치해도 의존 패키지 네 개(certifi, charset-normalizer, idna, urllib3)가 따라오므로, 그림 3처럼 다섯 줄이 나옵니다.

다른 컴퓨터에서 같은 환경이 필요하거나 망가진 환경을 지운 뒤에는, 새 가상환경을 만들어 활성화하고 python -m pip install -r requirements.txt를 실행합니다.

가상환경 비활성화·삭제와 Git 제외

가상환경에서 나오려면 deactivate를 입력합니다(터미널을 닫아도 같습니다). venv에는 제거 명령이 없으니 비활성화한 뒤 폴더를 지웁니다.

• PowerShell: Remove-Item -Recurse -Force .venv
• 명령 프롬프트: rmdir /s /q .venv
• macOS·Linux: rm -rf .venv

파일 탐색기나 Finder에서 지워도 됩니다. 코드와 requirements.txt는 그대로 남으므로 생성·활성화·설치만 다시 하면 됩니다. 프로젝트 폴더를 옮기거나 이름을 바꿨을 때도 마찬가지입니다. 환경 안 파일에는 절대 경로가 들어 있어서, 고치기보다 새로 만드는 편이 빠르고 안전합니다.

Git을 쓴다면 프로젝트의 .gitignore에 .venv/ 한 줄을 추가하세요. 3.13 이상은 환경 폴더 안에 무시 파일을 자동으로 만들지만, 이 한 줄이 있으면 낮은 버전을 쓰는 팀원도 보호됩니다.

venv 오류 해결: 활성화가 안 될 때

실행 정책을 영구히 바꾸고 싶지 않다면 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process를 쓰세요. 그 PowerShell 창을 닫을 때까지만 적용됩니다.

자주 묻는 질문

폴더 이름은 venv와 .venv 중 무엇이 좋나요?

둘 다 공식 문서가 인정하는 관례입니다. Python Packaging User Guide는 .venv를 쓰고, 앞의 점은 macOS·Linux의 일반 폴더 목록에서 폴더를 숨겨 줍니다. .gitignore에도 같은 이름을 적으세요.

가상환경에서 다른 파이썬 버전을 쓸 수 있나요?

가상환경은 항상 자신을 만든 파이썬을 씁니다. 3.12 환경이면 그 인터프리터로 만드세요. Windows 런처는 py -3.12 -m venv .venv, macOS·Linux는 python3.12 -m venv .venv이며 해당 버전이 설치되어 있어야 합니다.

코드가 가상환경 안인지 확인하려면?

sys.prefix != sys.base_prefix가 True이면 가상환경 안입니다. VIRTUAL_ENV 변수는 활성화할 때만 설정되고 활성화는 선택 사항이므로, 이 값에 의존하지 마세요.

참고 자료: 파이썬 문서: venv, 파이썬 자습서: 가상 환경 및 패키지, Python Packaging User Guide: pip와 venv, Microsoft Learn: 실행 정책

함께 읽으면 좋은 글

• Windows 64비트에 Python 설치하고 버전 확인하기
• Git status 읽기: 수정·스테이징·추적되지 않은 파일 구분