Python venv는 Python 프로젝트를 시작할 때 가장 먼저 익혀야 할 환경 관리 기본기입니다. 처음에는 그냥 pip install만 해도 되는 것처럼 보이지만, 프로젝트가 둘 이상이 되는 순간 패키지 버전 충돌이 생깁니다.
이 글에서는 venv는 프로젝트별 격리, requirements.txt는 환경 재현을 맡는다는 기준으로 설명합니다. pyproject.toml 같은 현대적인 설정 파일도 중요하지만, 입문 단계에서는 이 둘을 먼저 이해해야 다음 단계가 편해집니다.
Python venv와 requirements.txt를 나누어 보는 법
전역 설치가 문제를 만드는 이유
전역 Python에 모든 패키지를 설치하면 처음에는 단순합니다. 하지만 프로젝트 A는 Django 4를 쓰고, 프로젝트 B는 Django 5를 쓰고, 예전 실습 코드는 더 오래된 버전을 요구할 수 있습니다. 이때 한 공간에 계속 덮어쓰듯 설치하면 어떤 프로젝트가 어떤 버전을 기준으로 돌아가는지 알기 어려워집니다.
더 큰 문제는 에러가 코드 문제인지 환경 문제인지 구분하기 어려워진다는 점입니다. 어제는 실행되던 코드가 오늘 다른 패키지를 설치한 뒤 갑자기 깨진다면, 초보자는 코드를 의심하지만 실제 원인은 의존성 충돌일 수 있습니다.
venv는 프로젝트마다 작은 방을 만드는 도구
Python 공식 문서는 venv를 사용해 독립된 가상 환경을 만들 수 있다고 설명합니다. 중요한 감각은 어렵지 않습니다. 프로젝트마다 별도의 방을 만들고, 그 방 안에 필요한 패키지만 설치하는 것입니다.
python -m venv .venv
source .venv/bin/activate
python -m pip install requestsmacOS나 Linux에서는 위처럼 활성화합니다. Windows라면 활성화 명령만 다릅니다. 핵심은 python -m pip install을 실행했을 때 지금 활성화된 .venv 안에 설치된다는 점입니다.
requirements.txt는 설치 목록을 공유하는 파일
venv가 내 컴퓨터의 격리 공간이라면, requirements.txt는 그 공간 안에 무엇이 설치되어야 하는지 적어둔 목록입니다. Python 공식 튜토리얼도 pip freeze > requirements.txt로 목록을 만들고, 다른 환경에서 pip install -r requirements.txt로 설치하는 흐름을 보여줍니다.
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt여기서 조심할 점은 pip freeze가 현재 환경에 설치된 패키지를 거의 그대로 내보낸다는 것입니다. 실습을 많이 한 환경에서 무심코 freeze하면 실제 프로젝트에 필요 없는 패키지까지 따라 들어갈 수 있습니다.
입문자가 자주 헷갈리는 지점
.venv폴더 자체는 보통 Git에 올리지 않는다.requirements.txt는 팀원이 같은 패키지를 설치할 수 있도록 Git에 올린다.- 가상환경을 활성화하지 않은 상태에서 설치하면 엉뚱한 Python에 패키지가 들어갈 수 있다.
- 배포 서버에서는 새 가상환경을 만들고 requirements.txt로 다시 설치하는 흐름이 자연스럽다.
pyproject.toml과는 어떻게 다를까
최근 Python 프로젝트에서는 pyproject.toml이 점점 중요해지고 있습니다. 다만 pyproject.toml은 빌드 설정, 패키지 메타데이터, 도구 설정까지 담는 더 넓은 파일입니다. 이 글의 초점은 입문자가 당장 겪는 패키지 설치와 재현 문제입니다.
그래서 처음에는 venv와 requirements.txt로 환경 격리와 재현 감각을 익히고, 프로젝트가 커지면 pyproject.toml, lock file, poetry, uv 같은 도구로 확장하는 순서가 자연스럽습니다.
작은 프로젝트에서 바로 적용하는 순서
처음부터 도구를 많이 붙일 필요는 없습니다. 개인 학습 프로젝트라면 저장소를 만들고, .venv를 만들고, 필요한 패키지를 설치하고, 실행이 확인된 뒤 requirements.txt를 남기는 정도면 충분합니다. 그 다음 README에 설치 순서를 적어두면 한 달 뒤 다시 열어도 훨씬 덜 막힙니다.
- 프로젝트 폴더를 만들고 Git 저장소를 초기화한다.
python -m venv .venv로 가상환경을 만든다.- 가상환경을 활성화한 뒤 필요한 패키지만 설치한다.
- 실행이 확인되면
python -m pip freeze > requirements.txt로 목록을 남긴다. - 다른 환경에서는
python -m pip install -r requirements.txt로 재현한다.
이 흐름을 습관으로 만들면 “내 컴퓨터에서는 되는데 다른 곳에서는 안 되는” 상황을 줄일 수 있습니다. 특히 블로그 예제, 크롤링 실습, FastAPI 실습처럼 패키지가 빠르게 늘어나는 프로젝트에서 효과가 큽니다.
requirements.txt를 관리할 때의 기준
requirements.txt는 한 번 만들고 끝나는 파일이 아닙니다. 패키지를 추가했다면 파일도 갱신해야 하고, 더 이상 쓰지 않는 패키지가 많아졌다면 정리해야 합니다. 입문 단계에서는 완벽한 lock file을 만들기보다 “현재 프로젝트가 실제로 필요로 하는 목록인가”를 점검하는 습관이 중요합니다.
또한 팀 프로젝트에서는 버전을 너무 느슨하게 두면 사람마다 다른 버전이 설치될 수 있고, 너무 오래 고정하면 보안 업데이트를 놓칠 수 있습니다. 그래서 requirements.txt는 실행 재현과 유지보수 사이에서 균형을 잡는 파일로 보는 편이 좋습니다.
정리
Python venv를 쓰면 프로젝트마다 패키지 충돌을 줄일 수 있고, requirements.txt를 남기면 다른 사람이나 서버가 비슷한 환경을 다시 만들 수 있습니다. 처음부터 완벽한 도구 체계를 고르려 하기보다, 먼저 “격리하고 기록한다”는 감각을 잡는 것이 중요합니다.
