파이썬 가상환경(venv) 구축 및 requirements.txt 의존성 관리 완벽 가이드

파이썬 venv 가상환경 구축 방법과 requirements.txt를 활용한 의존성 패키지 관리, 파워쉘 스크립트 실행 오류 해결법을 정리합니다.

파이썬으로 다양한 프로젝트를 진행하다 보면 라이브러리 간의 버전 충돌 문제를 필연적으로 마주하게 됩니다. 전역(Global) 환경에 모든 패키지를 무분별하게 설치하면 특정 프로젝트는 최신 라이브러리를 요구하고 다른 프로젝트는 구버전을 요구할 때 시스템 전체의 파이썬 환경이 망가질 수 있습니다.

파이썬 표준 라이브러리에 내장된 venv 모듈을 사용하면 프로젝트마다 독립된 실행 환경을 구축하여 이러한 의존성 충돌을 사전에 방지할 수 있습니다. 가상환경 생성부터 활성화, 그리고 requirements.txt를 통한 버전 동기화 방법까지 단계별로 정리합니다.

1. 가상환경(Virtual Environment)의 개념과 필요성

파이썬의 가상환경은 특정 프로젝트만을 위한 독립된 파이썬 실행 바이너리와 패키지 디렉터리를 격리된 폴더 안에 생성하는 기술입니다.

버전 충돌 방지: 프로젝트 A(Django 3.x)와 프로젝트 B(Django 5.x)가 동일한 PC에서 서로 간섭 없이 독립적으로 동작합니다.
손쉬운 배포 및 협업: 프로젝트에 실제로 사용된 라이브러리 목록만 추출하여 팀원이나 운영 서버에 동일한 환경을 그대로 복제할 수 있습니다.
시스템 파이썬 보호: OS 기본 시스템이 참조하는 파이썬 환경을 건드리지 않아 운영체제 레벨의 스크립트 오류를 예방합니다.

2. venv 가상환경 생성 및 활성화

파이썬 3.3 버전 이후부터는 별도의 외부 패키지 설치 없이 표준 라이브러리의 venv를 바로 사용할 수 있습니다. 터미널(또는 명령 프롬프트)을 열고 프로젝트 작업 디렉터리로 이동한 뒤 진행합니다.

1) 가상환경 생성

작업 폴더 내에서 다음 명령어를 실행합니다. 마지막의 .venv는 생성될 가상환경 폴더의 이름입니다.

# Windows / macOS / Linux 공통
python -m venv .venv

명령어를 실행하면 현재 디렉터리에 .venv라는 폴더가 생성되며, 그 내부에 해당 가상환경 전용 파이썬 인터프리터와 site-packages 디렉터리가 구성됩니다.

2) 가상환경 활성화 (Activate)

가상환경을 생성한 후에는 터미널 세션이 해당 가상환경을 바라보도록 활성화해야 합니다. 운영체제에 따라 실행 명령어가 다릅니다.

# Windows (명령 프롬프트 - CMD)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# macOS / Linux (Bash or Zsh)
source .venv/bin/activate

활성화에 성공하면 터미널 프롬프트 맨 앞에 (.venv)와 같이 가상환경 이름이 표시됩니다. 이 상태에서 실행되는 모든 pip install 명령어는 전역 환경이 아닌 .venv 디렉터리 내부에만 패키지를 설치합니다.

3. 의존성 패키지 관리와 requirements.txt 활용

개발이 완료되었거나 협업을 위해 환경을 공유할 때는 설치된 패키지 목록을 문서화해야 합니다. 가상환경 폴더 자체는 용량이 크고 OS 종속적이므로 깃(Git) 등의 저장소에 올리지 않고, 텍스트 형태의 명세서인 requirements.txt만 공유하는 것이 표준입니다.

1) 현재 환경의 패키지 목록 내보내기 (Freeze)

가상환경이 활성화된 상태에서 아래 명령어를 실행하면 설치된 모든 라이브러리와 정확한 버전 정보가 텍스트 파일로 저장됩니다.

pip freeze > requirements.txt

생성된 requirements.txt 내부 구조 예시:

certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.1

2) requirements.txt 기반 일괄 설치

새로운 환경이나 다른 컴퓨터에서 동일한 가상환경을 복원할 때는 가상환경 생성 및 활성화 후 다음 명령어를 실행합니다.

pip install -r requirements.txt

이 명령어 하나로 파일에 명시된 모든 라이브러리가 동일한 버전으로 자동 설치됩니다.

4. 자주 발생하는 오류 및 트러블슈팅

1) Windows PowerShell 스크립트 실행 오류

Windows PowerShell에서 activate 스크립트 실행 시 보안 정책 제한으로 인해 오류가 발생할 수 있습니다.

오류 메시지: 이 시스템에서 스크립트를 실행할 수 없으므로… Activate.ps1 파일을 로드할 수 없습니다.
원인: Windows 기본 보안 정책상 서명되지 않은 스크립트의 실행이 차단되어 발생합니다.
해결법: PowerShell을 관리자 권한으로 실행한 뒤, 실행 정책을 RemoteSigned로 변경합니다.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

2) global 환경과 충돌하여 pip 경로가 꼬이는 경우

가상환경을 활성화했음에도 패키지가 전역 환경에 설치되는 경우가 있습니다.

점검법: 현재 터미널이 참조하는 파이썬과 pip의 실제 경로를 확인합니다.

# Windows
where python
where pip

# macOS / Linux
which python
which pip

출력 경로의 최상단이 현재 프로젝트의 .venv 폴더 내부를 가리키고 있지 않다면, 가상환경을 deactivate 한 후 다시 활성화 명령어를 입력해야 합니다.

5. 가상환경 비활성화 및 삭제

작업을 완전히 마친 후 가상환경에서 빠져나오려면 터미널에 다음 명령어를 입력합니다.

deactivate

프롬프트 앞의 (.venv) 표시가 사라지며 전역 환경으로 복귀합니다. 가상환경을 완전히 삭제하고 싶다면 복잡한 언인스톨 과정 없이 프로젝트 폴더 내의 .venv 디렉터리를 그대로 삭제하면 됩니다.

6. 요약 및 마무리

파이썬 가상환경은 안정적인 프로젝트 개발과 배포의 가장 기본이 되는 도구입니다.

프로젝트 생성 시 항상 python -m venv .venv로 격리된 환경을 만듭니다.
패키지 설치 및 실행 전 터미널 프롬프트의 (.venv) 표시를 반드시 확인합니다.
작업 완료 후 pip freeze > requirements.txt로 의존성 명세를 최신화합니다.