파이썬 가상환경(venv) 생성·실행·VS Code 연결 완벽 정리

파이썬을 처음 배울 때는 pip install로 라이브러리를 그냥 컴퓨터 전체에 깔게 됩니다. 프로젝트가 하나일 때는 문제가 없지만, 두 번째 프로젝트가 다른 버전의 같은 라이브러리를 요구하는 순간부터 충돌이 시작됩니다. 예를 들어 A 프로젝트는 어떤 라이브러리의 1.x 버전을 쓰는데 B 프로젝트는 2.x가 필요하다면, 하나를 설치하는 순간 나머지가 깨집니다.

가상환경은 이 문제를 프로젝트 폴더 안에 라이브러리 보관함을 따로 두는 방식으로 해결합니다. 각 프로젝트가 자기 보관함만 바라보기 때문에 서로 간섭하지 않습니다. 저도 12개 사이트를 1인으로 굴리면서 일부는 데이터 가공 스크립트를 파이썬으로 돌리는데, 사이트마다 venv를 따로 두지 않았다면 라이브러리 버전 충돌로 진작에 발목을 잡혔을 겁니다. 정리하면 venv는 격리, 재현, 청소 세 가지를 챙겨 줍니다.

좋은 소식은 venv가 파이썬에 기본 내장돼 있다는 점입니다. 따로 설치할 게 없습니다. 프로젝트 폴더로 이동한 뒤 아래 명령 한 줄을 치면 그 자리에 가상환경 폴더가 생깁니다. 관례상 폴더 이름은 venv 또는 .venv로 둡니다. 저는 VS Code가 자동으로 잘 찾도록 .venv를 선호하는데, 이 이유는 뒤에서 다시 짚겠습니다.

맥이나 리눅스에서는 python 대신 python3를 써야 하는 경우가 많습니다. 시스템에 따라 python 명령이 구버전(2.x)을 가리키거나 아예 없을 수 있기 때문입니다. 명령이 안 먹히면 python3 -m venv .venv로 바꿔서 시도하면 됩니다. 윈도우에서 파이썬을 공식 설치 프로그램으로 깔았다면 py 런처도 함께 들어오므로, 여러 버전을 깔아 둔 경우 py -3.12 -m venv .venv 처럼 버전을 콕 집어 만들 수도 있습니다.

가상환경을 만든 것만으로는 아무 일도 일어나지 않습니다. 활성화(activate)를 해야 그때부터 pip install이 그 보관함 안으로 들어갑니다. 그런데 이 활성화 명령이 운영체제와 셸 종류에 따라 제각각이라 초보자분들이 가장 많이 헷갈리는 지점입니다. 아래 표에 셸별로 정리했습니다.

활성화가 제대로 됐는지는 터미널 프롬프트 맨 앞에 (.venv) 같은 괄호 표시가 붙는지로 알 수 있습니다. 이 표시가 보이면 지금 이 가상환경 안에서 작업하고 있다는 뜻입니다. 활성화를 끝낼 때는 운영체제와 무관하게 deactivate 한 단어만 치면 됩니다.

여기가 한국에서 윈도우를 쓰는 개발자분들이 가장 많이 부딪히는 함정입니다. 분명히 가상환경을 만들었고 명령도 맞게 쳤는데, PowerShell에서 Activate.ps1을 실행하면 빨간 글씨로 이 시스템에서 스크립트를 실행할 수 없으므로 같은 에러가 뜹니다. 영문 환경이면 cannot be loaded because running scripts is disabled on this system 문구가 나옵니다.

이건 venv가 잘못된 게 아니라, 윈도우 PowerShell의 실행정책(execution policy)이 보안상 .ps1 스크립트 실행을 기본으로 막아 둔 탓입니다. 저도 새 윈도우 노트북을 받을 때마다 매번 겪는 통과의례라, 이제는 venv를 만들자마자 먼저 이 정책부터 풀어 둡니다. 해결은 아래 명령 한 줄이면 됩니다.

여기서 범위를 CurrentUser로 둔 게 핵심입니다. 시스템 전체(LocalMachine)에 적용하려면 관리자 권한 PowerShell이 필요하고 회사·학교 PC에서는 정책상 막혀 있을 수도 있습니다. 반면 CurrentUser는 내 계정에만 적용되어 권한 문제 없이 통과되는 경우가 많습니다. RemoteSigned는 내가 직접 만든 로컬 스크립트는 허용하되 인터넷에서 받은 서명 없는 스크립트는 막는, 적당히 안전한 절충값입니다. 굳이 모든 스크립트를 허용하는 값으로 풀 필요는 없습니다.

두 번째 단골 함정이 VS Code에서 인터프리터가 안 잡히는 케이스입니다. 가상환경은 분명 만들었는데, VS Code로 파이썬 파일을 열어 보면 여전히 전역 파이썬을 바라보고 있어서 venv에 깐 라이브러리를 못 찾는 import 에러가 나는 상황입니다. 핵심은 VS Code에게 이 프로젝트는 이 venv를 쓴다고 알려 주는 인터프리터 선택 단계입니다.

순서는 이렇습니다. 먼저 파이썬 확장(Python extension)이 설치돼 있어야 합니다. 그다음 단축키 Ctrl+Shift+P(맥은 Cmd+Shift+P)로 명령 팔레트를 열고 Python: Select Interpreter를 검색해 실행하면, 현재 프로젝트에서 찾은 인터프리터 목록이 뜹니다. 여기서 경로에 .venv가 포함된 항목을 고르면 됩니다. 보통 추천(Recommended) 라벨이 붙어 맨 위에 나옵니다.

그런데 막상 목록에 방금 만든 venv가 안 보이는 경우가 있습니다. 이때 점검할 순서를 정리하면 다음과 같습니다.

1. 폴더 이름 확인: 가상환경 폴더가 venv 또는 .venv여야 자동 감지가 잘 됩니다. 엉뚱한 이름이면 못 찾을 수 있습니다.
2. VS Code를 프로젝트 폴더로 열었는지: 상위 폴더를 통째로 열면 venv 위치가 어긋납니다. venv가 있는 폴더를 루트로 열어야 합니다.
3. 창 새로고침: 명령 팔레트에서 Developer: Reload Window를 한 번 실행하면 인터프리터를 다시 스캔합니다.
4. 경로 직접 입력: 그래도 안 보이면 Select Interpreter 목록 맨 위의 Enter interpreter path로 .venv 안의 파이썬 실행파일 경로를 직접 지정합니다.

인터프리터를 제대로 고르면 VS Code 우측 하단(또는 상태바)에 선택된 venv 이름이 표시되고, 새로 여는 통합 터미널은 자동으로 그 venv를 활성화한 상태로 열립니다. 이 자동 활성화 덕분에 터미널을 열 때마다 activate를 손으로 칠 필요가 사라집니다.

가상환경의 진짜 가치는 다른 환경에서 똑같이 되살릴 수 있다는 점에서 나옵니다. 지금 venv에 깔린 라이브러리 목록을 파일 하나로 뽑아 두면, 다른 PC나 서버에서 그 목록만 보고 동일하게 설치할 수 있습니다. 이 목록 파일이 관례적으로 requirements.txt입니다. 저도 사이트 배포 서버를 새로 잡을 때 이 파일 하나로 환경을 그대로 복제합니다.

여기서 자주 하는 실수가 가상환경 폴더(.venv) 자체를 깃허브에 올리는 것입니다. venv 폴더는 운영체제별로 내용이 다르고 용량도 크기 때문에 절대 올리면 안 됩니다. .gitignore에 .venv를 추가해 제외하고, 대신 requirements.txt만 올리는 게 정석입니다. 협업자는 이 파일만 받아 자기 환경에서 새로 venv를 만들고 install하면 동일한 라이브러리 구성이 됩니다.

참고로 요즘은 더 빠른 설치 도구나 의존성 잠금 파일을 쓰는 흐름도 있지만, 표준 라이브러리로 충분한 입문 단계에서는 venv + pip freeze 조합이 가장 단순하고 어디서나 동작합니다. 도구를 늘리기 전에 이 기본기를 먼저 손에 익히는 걸 권합니다.

제가 주변 입문자분들의 화면을 봐 주면서 반복적으로 마주친 실수를 빈도순으로 정리하면 다음과 같습니다. 대부분 venv 자체의 문제가 아니라 활성화를 빼먹거나 환경을 헷갈린 데서 옵니다.

이 다섯 가지만 머릿속에 넣어 두면 venv 관련 막힘의 9할은 스스로 진단할 수 있습니다. 특히 첫 줄, 즉 활성화 누락이 압도적으로 흔하니 import 에러가 나면 가장 먼저 프롬프트 앞의 (.venv) 표시부터 확인하는 습관을 들이시면 됩니다.

참고 자료

• 파이썬 공식 venv 문서 (docs.python.org/3/library/venv.html) — venv 생성·활성화·구조에 대한 표준 레퍼런스
• 마이크로소프트 Set-ExecutionPolicy 문서 (learn.microsoft.com) — PowerShell 실행정책 범위와 값의 의미
• VS Code 파이썬 환경 문서 (code.visualstudio.com/docs/python/environments) — 인터프리터 선택과 venv 자동 감지 설정