파이썬 가상환경 venv 완벽 정리: 생성부터 requirements.txt까지

가상 환경이 해결해 주는 문제

파이썬을 설치하고 pip install requests를 실행하면, 패키지는 시스템 전체에 공유되는 한 곳에 설치됩니다. 프로젝트가 하나뿐일 때는 별문제 없습니다. 그런데 프로젝트가 세 개쯤 되면 슬슬 골치 아파집니다.

• 프로젝트 A는 django==3.2가 필요하고, 프로젝트 B는 django==5.0이 필요합니다. 전역으로는 둘 중 하나밖에 설치할 수 없죠.
• 새로운 라이브러리를 한번 써 보고 싶은데, 다른 모든 프로젝트까지 오염시키고 싶지는 않습니다.
• 동료가 저장소를 클론했는데, 어떤 패키지를 어떤 버전으로 썼는지 알 길이 없습니다.

이럴 때 쓰는 게 바로 가상 환경(virtual environment) 입니다. 파이썬 인터프리터와 전용 라이브러리 설치 경로를 함께 담아 두는 독립된 폴더라고 보면 됩니다. 가상 환경을 활성화(activate) 하면 터미널에서 python과 pip가 시스템 파이썬 대신 이 폴더 안을 가리키게 됩니다. 여기에 설치한 패키지는 여기 안에만 머물고요.

venv로 가상 환경 만들기

venv는 파이썬 3에 기본 내장돼 있어서 따로 설치할 필요가 없습니다. 프로젝트 디렉터리 안에서 이렇게 실행하면 됩니다.

python3 -m venv .venv

이 명령을 실행하면 코드 옆에 .venv/ 폴더가 생성됩니다. .venv라는 이름은 사실상 표준 관례인데요, 앞에 점(.)이 붙어 있어서 대부분의 디렉터리 목록에서 숨겨지고, VS Code 같은 에디터가 자동으로 인식해 준다는 장점이 있습니다.

명령이 끝나면 이 폴더 안에 완전한 파이썬 런타임(수십 MB 정도인데, 원래 그 정도 크기입니다)과 전용 pip이 들어 있습니다.

가상환경 활성화하기

가상환경을 활성화하면 셸의 PATH가 바뀌면서 python과 pip 명령이 .venv/ 안에 있는 실행 파일을 가리키게 됩니다. 활성화 명령은 운영체제마다 다릅니다:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

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

가상 환경이 활성화되면 프롬프트 앞에 (.venv) 표시가 붙습니다. 지금 활성화된 상태라는 걸 한눈에 알려주는 장치죠. 이 상태에서 pip install을 실행하면 설치한 패키지는 오직 이 프로젝트에만 적용됩니다.

작업이 끝나면 deactivate 명령으로 원래 상태로 돌아갈 수 있습니다:

deactivate

터미널을 닫기 전에 굳이 비활성화할 필요는 없습니다. 셸을 종료하면 자동으로 해제되니까요.

패키지 설치하기

가상환경이 활성화된 상태에서 필요한 패키지를 설치하면 됩니다:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

현재 설치된 패키지는 pip list로 확인할 수 있고, 제거할 때는 pip uninstall requests처럼 쓰면 됩니다.

설치된 패키지들은 .venv/lib/pythonX.Y/site-packages/ 아래에 자리잡습니다. 이 디렉터리는 직접 손댈 일이 없고, 전부 pip이 알아서 관리해 줍니다.

requirements.txt로 의존성 버전 고정하기

내 프로젝트가 재현 가능하려면, 다른 사람도 내가 쓰던 것과 똑같은 버전을 설치할 수 있어야 합니다. 이를 가장 간단하게 기록해 두는 방법이 바로 requirements.txt입니다.

pip freeze > requirements.txt

pip freeze는 설치된 모든 패키지를 정확한 버전과 함께 출력합니다. 이 파일을 git에 커밋해 두세요.

그러면 협업하는 동료(또는 새 컴퓨터에서 작업을 이어가는 미래의 나)가 레포를 클론했을 때:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

세 가지 명령어면 충분하고, 실행 환경도 여러분의 환경과 동일하게 유지됩니다.

일반적인 프로젝트 세팅 예시

프로젝트 시작부터 마무리까지의 전체 작업 흐름은 다음과 같습니다:

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

.gitignore에 .venv 추가하기

.venv/ 폴더는 절대 커밋하지 마세요. 운영체제마다 내용이 달라지는 데다, requirements.txt만 있으면 언제든 똑같이 다시 만들 수 있거든요:

# .gitignore
.venv/
__pycache__/
*.pyc

커밋해 버리면 저장소만 비대해지고, 다른 컴퓨터에서는 제대로 동작하지 않을 뿐더러, 현재 OS에 맞춰 빌드된 바이너리들까지 그대로 노출됩니다.

어떤 파이썬 버전을 써야 할까?

기본적으로 python3 -m venv .venv는 셸에서 python3로 잡히는 파이썬을 그대로 사용합니다. 여러 버전(예: 3.12와 3.13)이 함께 설치되어 있다면, 어떤 버전을 쓸지 명시적으로 지정하는 게 좋습니다:

python3.13 -m venv .venv

venv가 한 번 만들어지면 그 안의 인터프리터는 고정됩니다. 활성화된 venv에서 python을 실행하면 시스템 Python 버전이 바뀌더라도 항상 그때 지정한 버전이 쓰인다는 뜻이죠.

문제가 생겼을 때

자주 마주치는 증상과 해결 방법을 정리해 봤습니다.

• pip install은 잘 되는데 import가 안 돼요. 엉뚱한 Python에 설치된 경우입니다. pip install 전에 venv를 먼저 활성화하고, macOS/Linux라면 which python, Windows라면 where python으로 어떤 파이썬이 잡혀 있는지 확인하세요.
• 활성화했는데 "ModuleNotFoundError"가 뜹니다. venv를 만들 때 특정 라이브러리가 빠졌거나, 패키지가 다른 venv에 설치된 경우예요. pip list로 지금 venv에 실제로 뭐가 깔려 있는지 확인할 수 있습니다.
• Windows에서 활성화 스크립트를 찾을 수 없다고 나옵니다. PowerShell이 서명되지 않은 스크립트를 막고 있을 수 있습니다. Set-ExecutionPolicy -Scope CurrentUser RemoteSigned를 한 번 실행해 로컬 스크립트 실행을 허용해 주세요.
• "No module named venv" 에러가 납니다. 일부 리눅스 배포판에서는 venv가 별도 패키지로 분리되어 있습니다. Debian/Ubuntu라면 sudo apt install python3-venv로 설치하세요.

venv 다음 단계: Poetry, uv, pipenv

venv + pip + requirements.txt 조합이 손에 익으면, 같은 개념을 좀 더 편하게 다룰 수 있도록 감싸주는 도구들을 만나게 됩니다.

• Poetry — venv, 의존성 관리, 패키징을 pyproject.toml 하나로 해결합니다.
• uv — 매우 빠른 pip 대체 도구로, venv 관리까지 해줍니다.
• pipenv — "Pipfile + Pipfile.lock" 패턴을 유행시킨 초창기 도구입니다.

셋 다 좋은 도구지만, 처음 배울 때는 필수가 아닙니다. 먼저 순정 venv 워크플로에 익숙해진 다음에 이런 도구들을 써보세요. 어디까지나 편의성 개선일 뿐입니다.

핵심 정리

• 제대로 된 Python 프로젝트라면 저마다 별도의 가상환경을 가집니다.
• python3 -m venv .venv로 만들고, 활성화한 뒤 자유롭게 pip install을 하세요.
• pip freeze > requirements.txt로 의존성을 고정하고, 이 파일은 커밋합니다.
• 반대로 .venv/ 폴더 자체는 절대 커밋하지 마세요.
• import가 이상하게 동작한다면, 먼저 지금 어떤 Python이 활성화되어 있는지부터 확인하세요.

다음 주제: __main__ 패턴

프로젝트를 구성하고 패키지까지 설치했으니, 이 장을 마무리할 관용구가 하나 남았습니다. 바로 if __name__ == "__main__" 가드입니다. 스크립트로 실행되는 거의 모든 Python 파일에 등장하는 패턴인데, 다음 페이지에서 자세히 다뤄보겠습니다.