Python venv와 .venv 사용법: 가상환경 생성과 인터프리터 확인

Python 프로젝트마다 패키지를 분리하려면 프로젝트 디렉터리에서 python -m venv .venv로 가상환경을 만들고, 그 환경의 Python으로 설치와 실행을 수행한다. .venv는 관례적인 디렉터리 이름이며 venv 모듈과 다른 기능이 아니다. 패키지를 설치했는데도 import 오류가 난다면 현재 실행 중인 인터프리터부터 확인한다.

프로젝트별 패키지 환경을 표현한 개념 이미지다.

이 글은 2026-11-13 기준 Python 공식 venv 문서를 바탕으로 한다. Linux의 Python 3.12.14에서 가상환경 생성과 인터프리터 확인을 실행했다. Windows 명령은 문서 기반이며 직접 실행하지 않았다.

1. venv와 .venv는 무엇이 다른가

venv는 표준 라이브러리의 가상환경 생성 모듈이다. .venv는 생성할 폴더의 이름일 뿐이며 venv나 다른 이름도 지정할 수 있다. 기본 설정에서 각 환경의 패키지는 다른 환경 및 시스템 패키지와 분리된다. 단, --system-site-packages를 쓰면 시스템 패키지에 접근할 수 있다.

가상환경은 보안 샌드박스가 아니다. 설치한 코드가 실행되는 프로세스는 실행 사용자의 권한을 가진다.

2. 원하는 Python으로 환경을 만든다

프로젝트 루트에서 실행한다. 생성에 사용한 Python이 해당 환경의 기반 버전을 결정하므로 먼저 버전을 확인한다.

Windows에서는 설치된 Python을 확인한 후 다음처럼 실행할 수 있다.

이미 존재하는 폴더를 지정하면 재사용된다. 기존 폴더에 프로젝트 파일이 없는지 확인하고, 삭제 기능이 있는 --clear를 무심코 사용하지 않는다. 배포판에 따라 venv 또는 ensurepip가 별도 패키지로 제공될 수 있으므로 생성 오류가 나면 해당 배포판의 안내를 확인한다.

3. 활성화하거나 인터프리터를 직접 지정한다

활성화는 현재 셸의 PATH 앞에 가상환경 실행 파일 경로를 추가하는 편의 기능이다. 셸을 새로 열면 다시 활성화해야 한다.

환경	활성화 명령
Linux·macOS bash/zsh	`source .venv/bin/activate`
Windows PowerShell	`.\.venv\Scripts\Activate.ps1`
Windows cmd	`.venv\Scripts\activate.bat`

종료할 때는 deactivate를 실행한다. PowerShell에서 실행 정책 때문에 스크립트가 차단된다면 조직 정책을 확인한다. 정책을 바꾸지 않고 인터프리터를 직접 지정할 수도 있다. 활성화 방법

app.py는 프로젝트의 실제 진입점으로 바꾼다. python -m pip는 지정한 Python에 연결된 pip를 사용하므로 별도 pip 명령이 다른 환경을 가리키는 혼동을 줄인다.

4. 설치했는데 import가 안 되면

실행한 Python의 경로와 가상환경 여부를 확인한다.

첫 줄은 실제 인터프리터 경로이고 True는 가상환경에서 실행 중이라는 뜻이다. pip 출력의 경로도 의도한 환경과 비교한다. IDE, 터미널, 서비스 실행 설정은 서로 다른 인터프리터를 사용할 수 있으므로 각각 확인한다. 프롬프트의 (.venv) 표시나 VIRTUAL_ENV만으로 판정하지 않는다. 직접 경로로 실행하면 활성화 없이도 가상환경을 사용할 수 있다.

필요한 패키지는 해당 인터프리터로 설치한다. 예를 들어 프로젝트가 requirements 파일을 제공한다면 다음과 같다.

설치 실패나 버전 충돌은 오류 메시지와 프로젝트의 Python·의존성 요구사항을 별도로 확인해야 한다.

5. 이동과 공유는 재생성으로 처리한다

가상환경 안의 실행 스크립트에는 절대 경로가 포함될 수 있어 폴더를 복사하거나 프로젝트를 옮긴 뒤 그대로 사용하는 것은 안전하지 않다. 의존성 정의를 보관하고 새 위치에서 환경을 다시 만든 다음 설치한다. .venv 자체는 일반적으로 Git에 커밋하지 않는다. Python 3.13부터 venv가 기본적으로 환경 안에 Git 무시 파일을 생성하지만, 팀 저장소의 ignore 정책도 확인한다. 공식 문서의 이동성 설명

직접 확인한 범위는 Linux에서의 환경 생성과 sys.prefix 비교다. 운영체제별 활성화 및 패키지 설치 예제는 공식 문서에 따른 설명이다.

English version: Python venv and .venv: Create an Environment and Check the Interpreter