virtual environment

파이썬 가상 환경(virtual environment)은 프로젝트마다 의존성을 분리하기 위한 가장 기본적인 도구다. 같은 라이브러리라도 버전이 다르면 동작이 달라질 수 있고, 한 프로젝트에서 업그레이드한 패키지가 다른 프로젝트를 깨뜨리는 상황이 흔하다. 가상 환경은 이런 충돌을 피하기 위해 “프로젝트별 패키지 공간”을 만들어준다. 결국 가상 환경은 편의가 아니라 재현성과 안정성을 위한 규약이다.

가상 환경은 설치 위치를 분리할 뿐만 아니라, 실행 시점에 어떤 파이썬과 패키지를 참조할지 결정한다. 그래서 활성화(activate)가 중요한데, 이는 PATH를 바꿔서 해당 환경의 python/pip를 우선 사용하게 만드는 동작이다. 이 구조를 이해하면 “왜 설치했는데 인식이 안 되지?” 같은 혼란을 줄일 수 있다.

# 가상 환경 생성
python -m venv .venv

# 활성화 (macOS/Linux)
source .venv/bin/activate

# 활성화 (Windows)
.venv\Scripts\activate

# 비활성화
deactivate

보통 프로젝트 루트에 .venv라는 이름으로 생성하는 것이 관례다. 숨김 폴더처럼 보이기 때문에 깔끔하고, IDE나 툴에서도 자동 인식하는 경우가 많다. 팀 단위에서는 “가상 환경 위치”를 통일하는 것만으로도 온보딩 비용을 줄일 수 있다.

의존성 고정과 requirements.txt

가상 환경을 만들었으면, 그 안에 어떤 패키지를 설치했는지 기록해야 한다. 가장 흔한 방식이 requirements.txt다. 이 파일은 “이 프로젝트를 재현하려면 어떤 패키지가 필요한가”를 정의하는 계약서다. 개발자가 여러 명이거나 배포 환경이 존재한다면, requirements.txt는 필수다.

단순히 pip freeze로 전부 기록하는 방식은 쉽지만, 의존성이 많아지면 불필요한 패키지까지 고정되는 문제가 있다. 그래서 실무에서는 직접 관리하는 requirements.txt와, 잠금 파일(예: pip-tools, poetry)을 분리해서 쓰는 경우가 많다. 중요한 건 “버전이 왜 고정됐는지”를 팀이 이해할 수 있게 만드는 것이다.

# 현재 환경의 패키지 목록 저장
pip freeze > requirements.txt

# 의존성 설치
pip install -r requirements.txt

requirements.txt는 편하지만 완벽하지 않다. 특히 개발용 의존성과 운영용 의존성을 구분해야 하는 경우가 많다. 이때는 requirements-dev.txt 같은 별도 파일로 나누는 게 실무적이다.

분리의 기준은 간단하다. 실행 환경에 반드시 필요한 패키지는 requirements.txt에 두고, 테스트/포맷터/린터 같은 도구는 requirements-dev.txt에 둔다. 이렇게 하면 배포 환경이 불필요한 패키지로 오염되지 않고, 설치 속도와 보안 위험도 줄어든다. 결국 의존성 분리는 “환경의 책임을 명확히 하는 설계”다.

# 운영용
pip install -r requirements.txt

# 개발용(운영 + 개발 도구)
pip install -r requirements.txt -r requirements-dev.txt

규모가 커질수록 requirements.txt만으로는 부족해진다. 이때는 pip-tools로 requirements.in → requirements.txt로 잠금 파일을 생성하는 방식이 안정적이다. 의존성의 “의도”와 “정확한 버전”을 분리해 관리할 수 있기 때문이다.

실무에서 흔한 함정

가장 흔한 실수는 “가상 환경을 활성화하지 않고 pip install을 실행하는 것”이다. 이 경우 전역 파이썬에 패키지가 설치되고, 프로젝트 환경에서는 패키지를 찾지 못한다. 그래서 항상 python -m pip로 설치하는 습관이 좋다. 현재 어떤 pip를 쓰는지 명확해지기 때문이다.

또 하나는 가상 환경을 git에 올려버리는 것이다. 가상 환경은 OS와 파이썬 버전에 종속되므로, 공유하면 오히려 문제가 커진다. 따라서 .venv는 .gitignore에 포함시키고, 대신 requirements.txt를 공유하는 것이 안전하다.

# 현재 사용 중인 파이썬/패키지 경로 확인
which python
python -m pip --version

가상 환경은 처음엔 귀찮아 보이지만, 프로젝트가 커질수록 반드시 필요한 인프라가 된다. 결국 “환경을 통제한다”는 감각이 파이썬 프로젝트의 안정성을 결정한다.

venv 외의 선택지

표준 라이브러리의 venv는 가장 가볍고 기본적인 선택이다. 하지만 프로젝트가 복잡해지면 pipenv나 poetry 같은 도구를 쓰기도 한다. 이들은 가상 환경 생성과 의존성 관리, 잠금 파일 생성을 통합해 제공한다. 결국 선택은 “단순함을 유지할 것인가, 자동화를 도입할 것인가”의 문제다.

pipenv는 Pipfile/Pipfile.lock으로 비교적 단순한 흐름을 제공하고, poetry는 pyproject.toml 기반으로 의존성, 빌드, 배포까지 일관된 워크플로를 제공한다. 즉, pipenv는 “가벼운 통합”, poetry는 “프로젝트 관리까지 포함한 통합”에 가깝다. 둘 다 좋은 도구지만, 팀의 크기와 배포 프로세스가 기준이 된다.

# pipenv
pipenv install requests
pipenv shell

# poetry
poetry init
poetry add requests
poetry install

핵심은 도구가 아니라 원칙이다. 어떤 도구를 쓰든 “프로젝트마다 환경을 분리하고, 의존성을 명시적으로 관리한다”는 원칙을 지키는 게 중요하다. 이 원칙이 무너지면, 프로젝트는 재현 가능한 형태를 잃는다.