가상환경을 안 쓰고 라이브러리를 설치했다가 다른 프로젝트가 깨진 이유

문제 발생

새 프로젝트에서 pip install requests==2.25.0을 실행했더니, 이전에 만들어둔 다른 프로젝트가 갑자기 실행되지 않았습니다. 그 프로젝트는 requests의 더 최신 버전에만 있는 기능을 쓰고 있었습니다.

원인 분석

가상환경을 쓰지 않으면 pip install은 시스템(또는 사용자) 전역 Python 환경에 패키지를 설치합니다. 한 컴퓨터에서 여러 프로젝트를 진행하면, 프로젝트마다 필요한 라이브러리 버전이 다를 수 있는데 전역 환경에는 패키지당 하나의 버전만 존재할 수 있습니다. 나중에 설치한 프로젝트의 요구사항이 이전 프로젝트가 의존하던 버전을 덮어써 버립니다.

이 문제는 프로젝트가 두 개만 넘어가도 거의 필연적으로 발생합니다 — 각 프로젝트의 requirements.txt가 서로 다른 버전을 요구하는 순간 전역 환경 하나로는 둘 다 만족시킬 수 없습니다.

해결 방안

1. 프로젝트마다 독립된 가상환경을 만듭니다. 표준 라이브러리에 포함된 venv로 별도 설치 없이 바로 쓸 수 있습니다.

python -m venv .venv          # 프로젝트 폴더에 가상환경 생성
source .venv/bin/activate     # 활성화 (Windows는 .venv\Scripts\activate)
pip install -r requirements.txt

2. 가상환경을 활성화한 상태에서 pip install을 하면, 그 설치는 전역이 아니라 .venv 폴더 안에만 격리되어 다른 프로젝트에 영향을 주지 않습니다.
3. 가상환경 폴더(.venv/)는 .gitignore에 추가하고, 대신 requirements.txt(또는 pyproject.toml)를 커밋해 "어떤 패키지가 필요한지"만 저장소에 남깁니다 — 다른 사람은 그 파일로 자기 가상환경에 똑같이 설치하면 됩니다.
4. 더 큰 프로젝트나 여러 Python 버전을 함께 관리해야 한다면 pyenv(Python 버전 자체를 관리), Poetry나 uv 같은 통합 의존성 관리 도구도 고려할 수 있습니다 — 다만 표준 라이브러리의 venv + pip만으로도 대부분의 상황은 해결됩니다.
5. 이미 전역 환경이 지저분해졌다면, 어떤 패키지가 전역에 깔려있는지 확인(pip list)하고 필요하다면 정리한 뒤, 앞으로는 가상환경 없이 pip install을 하지 않는 습관을 들이는 것이 가장 확실합니다.

공식 문서

• Python Docs: venv — Creation of virtual environments
• Python Packaging User Guide: Installing packages using pip and virtual environments