python venv 가상환경 — Python venv 가상환경 사용법: 3.14 생성·활성화·확인 정리

Python venv 가상환경 사용법: 3.14 생성·활성화·확인 정리

2026.11.14 · 19분 읽기

프로젝트마다 패키지 버전이 다르면 시스템 Python 하나로는 의존성이 충돌한다. Python venv 가상환경은 프로젝트별로 독립된 인터프리터 실행 경로와 site-packages를 두는 표준 라이브러리 기능이다. 이 글은 Python 3.14 venv 모듈 문서와 Python 3.14 튜토리얼의 가상환경 장을 기준으로 생성, 활성화, 확인, 종료까지의 순서를 정리한다(2026-10 기준).

진행 순서는 다음과 같다. 먼저 인터프리터 버전을 확인하고 python -m venv로 환경을 만든 뒤, 쓰는 셸에 맞는 스크립트로 활성화한다. 실제 사용 여부는 sys.prefix != sys.base_prefix로 판정한다. 각 단계에서 무엇을 보면 성공인지도 함께 적었다.

목차

Python venv 가상환경의 적용 범위와 버전

이 글은 Python 3.14 문서에 실린 표준 라이브러리 venv 모듈을 다룬다. 별도 패키지를 설치하지 않고 인터프리터에 포함된 모듈을 쓰는 방식이다.

지원하지 않는 플랫폼부터 확인한다. venv 문서의 Availability 항목에는 "not Android, not iOS, not WASI"라고 적혀 있다. 모바일 플랫폼과 WebAssembly 플랫폼에서는 이 모듈을 지원하지 않는다는 뜻이다. 데스크톱과 서버 환경, 즉 POSIX 계열(Linux, macOS)과 Windows가 이 글의 대상이다.

가상환경의 Python 버전은 명령을 실행한 인터프리터가 정한다. 튜토리얼은 "venv will install the Python version from which the command was run"이라고 설명하고, python3.12로 실행하면 3.12 환경이 만들어진다는 예를 든다. 그러므로 3.14 가상환경을 원한다면 반드시 3.14 인터프리터로 python -m venv를 실행해야 한다. 이미 만든 환경을 갱신하는 --upgrade 옵션이 있지만, 문서는 이 옵션이 Python을 제자리(in-place)에서 업그레이드한 경우를 가정한다고 적는다. 다른 버전의 Python이 필요하면 그 인터프리터로 환경을 다시 만든다.

문서가 명령을 제시하는 셸은 여섯 가지다.

  • POSIX: bash/zsh, fish, csh/tcsh, pwsh(PowerShell)
  • Windows: cmd.exe, PowerShell

셸에 따라 활성화 스크립트가 다르므로, 활성화 단계에서 해당하는 행만 골라 쓰면 된다.

시작 전 준비: 인터프리터 버전과 디렉터리 위치

준비할 것은 세 가지다. 지원 플랫폼인지는 앞 절에서 확인했으니, 남은 두 가지는 인터프리터 버전과 가상환경 디렉터리 위치다.

인터프리터 버전 확인

터미널에서 python --version을 실행해 출력된 버전이 3.14인지 본다. venv가 설치하는 Python 버전은 바로 이 --version 옵션이 보고하는 버전이다. 시스템에 여러 버전이 설치되어 있으면 python이 가리키는 인터프리터가 의도한 것과 다를 수 있다. 3.14가 아니라면 3.14 인터프리터를 직접 지정해 실행한다.

디렉터리 이름과 위치 정하기

venv 문서에 따르면 가상환경은 보통 프로젝트 디렉터리 안의 .venv나 venv에 둔다. 가상환경이 많다면 ~/.virtualenvs 같은 컨테이너 디렉터리 아래에 모으는 방식도 문서에 나온다.

튜토리얼은 .venv를 흔한 위치로 소개하면서 이유를 하나 더 든다. 일부 도구가 쓰는 .env 환경변수 정의 파일과 이름이 겹치지 않는다는 점이다. 특별한 이유가 없다면 프로젝트 루트의 .venv가 무난한 선택이다.

권한 요구사항
Windows PowerShell에서 활성화 스크립트를 실행하려면 사용자 범위의 실행 정책 설정이 필요할 수 있으며, 이 내용은 활성화 절에서 다룬다.

python -m venv로 가상환경 생성하기

venv-create-capsule

생성 명령의 형식은 플랫폼마다 경로 표기만 다르다. POSIX에서는 python -m venv /path/to/new/virtual/environment, Windows PowerShell에서는 PS> python -m venv C:\path\to\new\virtual\environment를 실행한다. 프로젝트 루트에서 .venv로 만든다면 python -m venv .venv 한 줄이면 된다.

아래는 bash/zsh 기준으로 버전 확인부터 종료까지 이어지는 전체 흐름이다.

python --version            # ← 3.14 인터프리터인지 먼저 확인
python -m venv .venv        # ← 프로젝트 루트에 .venv 생성
source .venv/bin/activate   # ← bash/zsh 활성화
python check_venv.py        # ← 가상환경 인터프리터로 실행 (확인 스크립트는 아래 절)
deactivate                  # ← 활성화 해제

생성 직후 디렉터리 확인

명령이 성공하면 대상 디렉터리 안에 아래 구조가 생긴다. 문서가 설명하는 생성 결과를 그대로 옮긴 것이다.

.venv/
├── pyvenv.cfg              ← home 키가 명령을 실행한 Python 설치를 가리킴
├── bin/                    ← Windows는 Scripts\
│   └── (Python 실행 파일의 복사본 또는 심볼릭 링크)
└── lib/pythonX.Y/site-packages/   ← Windows는 Lib\site-packages

세 항목이 모두 있으면 생성 단계는 끝난 것이다. pyvenv.cfg를 열어 home 값이 3.14 설치 경로를 가리키는지도 함께 보면 엉뚱한 인터프리터로 만들었는지 바로 드러난다.

실행 파일을 복사본으로 둘지 심볼릭 링크로 둘지는 플랫폼과 생성 시 인자에 따라 정해진다. 기본 동작을 바꾸는 옵션은 두 개다. --symlinks는 플랫폼 기본이 링크가 아닐 때 링크를 시도하고, --copies는 플랫폼 기본이 링크일 때도 복사를 시도한다.

생성 명령에는 알아 둘 동작이 두 가지 더 있다. 상위 디렉터리가 없으면 함께 만들어지고, 이미 존재하는 디렉터리를 지정하면 그 디렉터리를 재사용한다. 깨끗한 상태에서 다시 만들고 싶다면 필요한 것은 재사용이 아니라 --clear 옵션이다. 이 옵션은 마지막 절에서 정리한다.

셸별 venv 활성화 명령과 PowerShell 실행 정책

venv-activate-shell-paths

활성화는 가상환경의 bin(Windows는 Scripts) 디렉터리를 PATH 앞에 추가하는 작업이다. 문서 원문은 "running python will invoke the environment’s Python interpreter"라고 설명한다. 활성화 뒤에는 python만 입력해도 가상환경 인터프리터가 실행되고, 환경에 설치한 스크립트도 전체 경로 없이 실행된다.

셸별 명령은 아래 표와 같다. <venv>는 가상환경 경로로 바꾼다. 앞 절 예시라면 .venv다.

플랫폼 셸 활성화 명령
POSIX bash/zsh source <venv>/bin/activate
POSIX fish source <venv>/bin/activate.fish
POSIX csh/tcsh source <venv>/bin/activate.csh
POSIX pwsh <venv>/bin/Activate.ps1
Windows cmd.exe <venv>\Scripts\activate.bat
Windows PowerShell <venv>\Scripts\Activate.ps1

튜토리얼은 같은 내용을 더 짧게 보여 준다. python -m venv tutorial-env로 만든 환경을 Windows에서는 tutorial-env\Scripts\activate, Unix/macOS에서는 source tutorial-env/bin/activate로 활성화한다.

활성화 성공 여부 1차 확인

튜토리얼에 따르면 활성화하면 셸 프롬프트가 바뀌어 사용 중인 가상환경 이름이 표시된다. 프롬프트에 환경 이름이 보이면 활성화 스크립트가 실행된 것이다. 다만 이 표시는 셸 쪽 신호일 뿐이므로, 인터프리터가 실제로 가상환경에서 실행되는지는 다음 절의 방법으로 확인한다.

Windows PowerShell에서 Activate.ps1이 막힐 때

Windows에서는 Activate.ps1 스크립트를 실행하려면 사용자 실행 정책을 설정해야 할 수 있다. 문서가 제시하는 명령은 PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser다.

실행 정책 변경 범위 주의
실행 정책은 PowerShell 스크립트 실행을 제한하는 보안 설정이므로, 문서 명령처럼 `-Scope CurrentUser`로 현재 사용자에게만 적용하고 정책 값은 `RemoteSigned`로 둔다. 문서 표현은 “may be required”로, 활성화가 막힐 때만 적용 대상이라는 뜻이다. 정책별 의미는 Python 문서가 연결하는 Microsoft의 About Execution Policies 문서에서 확인한다.

가상환경 확인: sys.prefix와 VIRTUAL_ENV의 차이

프롬프트 표시나 환경변수보다 정확한 판정 기준이 있다. 문서에 따르면 가상환경에서 실행 중인 인터프리터는 sys.prefix와 sys.exec_prefix가 가상환경 디렉터리를 가리키며, sys.base_prefix와 sys.base_exec_prefix는 환경을 만들 때 쓴 기본 Python을 가리킨다. 문서는 "It is sufficient to check sys.prefix != sys.base_prefix"라고 명시한다. 두 값이 다르면 가상환경 인터프리터다.

확인용 스크립트를 check_venv.py로 저장해 실행한다.

import os
import sys


def running_in_venv() -> bool:
    return sys.prefix != sys.base_prefix   # ← 문서가 제시하는 판정식


print("sys.prefix      :", sys.prefix)
print("sys.base_prefix :", sys.base_prefix)
print("가상환경 실행 여부:", running_in_venv())
print("VIRTUAL_ENV     :", os.environ.get("VIRTUAL_ENV"))  # ← 활성화했을 때만 설정됨

활성화한 셸에서 python check_venv.py를 실행하면 sys.prefix 쪽에 .venv 경로가 찍히고 판정 결과가 True로 나와야 정상이다. 활성화하지 않은 셸에서 시스템 python으로 실행하면 두 경로가 같아지고 판정은 False가 된다.

VIRTUAL_ENV를 판정 기준으로 쓰지 않는 이유

VIRTUAL_ENV 환경변수는 가상환경을 활성화했을 때 환경 경로로 설정된다. 가상환경은 활성화하지 않고도 쓸 수 있다. 그래서 문서는 이 변수를 가상환경 사용 여부를 판단하는 근거로 삼을 수 없다고 적는다. 위 스크립트를 활성화 없이 .venv/bin/python check_venv.py처럼 전체 경로로 실행하면 판정은 가상환경을 가리키지만 VIRTUAL_ENV는 비어 있을 수 있다. 두 값을 나란히 출력한 것도 이 차이를 직접 보기 위해서다.

활성화 없이 쓰기와 deactivate로 종료하기

활성화는 선택 사항이다. 문서는 Python을 호출할 때 그 환경 인터프리터의 전체 경로를 지정하면 된다고 설명한다. POSIX에서는 .venv/bin 아래의 인터프리터를, Windows에서는 .venv\Scripts 아래의 인터프리터를 경로째 실행하는 방식이다. 환경에 설치한 스크립트도 활성화 없이 실행되도록 만들어진다. 셸 설정을 건드리기 어려운 cron 작업이나 CI 스크립트에서는 이 방식이 더 단순하다.

Windows 탐색기에서 설치된 스크립트를 더블클릭해 올바른 인터프리터로 실행하는 동작에는 조건이 붙는다. Python install manager가 설치되어 있을 때 shebang 줄 처리가 지원된다는 것이 문서의 설명이다. install manager가 없는 환경이라면 이 동작을 전제로 삼지 않는다.

종료는 셸에서 deactivate를 입력하는 것으로 끝난다. 구체적인 메커니즘은 플랫폼마다 다르고 내부 구현 사항이며, 보통 스크립트나 셸 함수로 구현된다고 문서는 적고 있다. 종료 후 프롬프트에서 환경 이름이 사라졌는지, check_venv.py의 판정이 False로 돌아왔는지 보면 해제 여부를 확인할 수 있다.

venv 가상환경 사용 시 주의사항

가상환경은 옮기지 말고 다시 만든다

venv 문서는 가상환경을 이동하거나 복사할 수 있는 대상으로 보지 않는다. 대상 위치에 같은 환경을 새로 만들라는 것이 문서의 지침이다. 이유는 shebang에 있다. 설치된 스크립트는 활성화를 전제하지 않으므로 shebang 줄에 환경 인터프리터의 절대 경로가 들어간다. 그래서 일반적인 경우 가상환경은 본질적으로 이식할 수 없다.

가상환경 자체가 아니라 상위 디렉터리를 옮긴 경우도 같다. 문서의 Warning은 이 경우에도 새 위치에서 환경을 다시 만들라고 하며, 그러지 않으면 설치된 소프트웨어가 예상대로 동작하지 않을 수 있다고 경고한다. 프로젝트 폴더 이름을 바꾸거나 다른 경로로 옮겼다면 기존 .venv를 지우고 새로 생성한다.

환경은 일회용, 코드는 밖에 둔다

문서는 가상환경을 "disposable"로 규정한다. 환경은 지우고 처음부터 다시 만들기 쉬워야 하며, 프로젝트 코드는 환경 밖에 두는 것이 원칙이다. 재생성을 반복할 수 있도록 설치 패키지 목록을 requirements.txt 같은 파일로 프로젝트에 남겨 두는 방식이 이 원칙과 맞는다.

Git 같은 버전 관리 시스템에도 가상환경을 넣지 않는다. Python 3.13부터는 venv가 Git용 .gitignore 파일을 기본으로 생성하는 방식이다. 이 파일이 필요 없다면 3.13에서 추가된 --without-scm-ignore-files 옵션으로 생성을 생략한다. 프로그램에서 venv 모듈을 쓰는 경우를 위해 같은 버전에 scm_ignore_files 매개변수도 추가됐다.

활성화해도 PYTHONPATH는 그대로다

튜토리얼은 활성화된 가상환경이 PYTHONPATH 변수를 전혀 바꾸지 않는다고 명시한다. 이 경로에 가상환경의 Python 버전과 호환되지 않는 코드가 들어 있으면 예상치 못한 결과가 생길 수 있다. 권장 방법은 bash 기준 unset PYTHONPATH이며, 다른 셸에서는 각 셸의 동등한 명령을 사용하는 방식이다. 해당 내용은 venv 모듈 문서가 아닌 튜토리얼에만 있다.

Windows 심볼릭 링크 비권장
Windows에서도 심볼릭 링크는 지원되지만 문서는 권장하지 않는다. 탐색기에서 `python.exe`를 더블클릭하면 링크가 즉시 해석되어 가상환경이 무시되기 때문이다. Windows에서는 `–symlinks`를 붙이지 않고 기본 동작을 유지하는 편이 안전하다.

튜토리얼 출력 예시의 버전

튜토리얼에 실린 세션 출력 예시는 Python 3.5.1 기준이다. 3.14에서 실제로 출력되는 버전 문자열이나 메시지는 예시와 다를 수 있으므로, 출력 문구를 그대로 비교하기보다 앞에서 설명한 디렉터리 구조와 sys.prefix 판정으로 확인한다.

venv 재생성 옵션과 이어지는 주제

환경을 고쳐 쓸 때 쓰는 옵션은 두 개다. --clear는 대상 디렉터리가 이미 있으면 그 내용을 지운 뒤 환경을 생성한다. 이미 있는 디렉터리를 그대로 재사용하는 기본 동작과는 다르다. --upgrade는 Python이 제자리(in-place)에서 업그레이드됐다고 가정하고, 환경 디렉터리가 그 버전의 Python을 쓰도록 갱신한다. 제자리 업그레이드가 아니라 다른 버전의 인터프리터를 쓰려면 앞 절에서 설명한 대로 그 인터프리터로 환경을 다시 만든다. 한국어 설명이 필요하면 Python 3.14 한국어판 venv 문서에서 같은 옵션 목록을 볼 수 있다.

가상환경을 만들고 확인하는 단계를 마쳤다면 이어지는 주제는 패키지 관리다. 같은 튜토리얼 장은 가상환경 안에서 pip로 패키지를 설치하고 requirements.txt로 목록을 고정하는 흐름을 다루며, 이는 앞서 말한 재생성 원칙과 직접 연결된다.

관련 글

이 글 공유하기