10강. 패키지 공유 이해
0. 학습 목표
→ 프로젝트를 다른 환경으로 옮길 때 무엇을 공유하고 무엇을 공유하지 않는지 기준을 세웁니다.
이번 글은 개념 중심 강의입니다.
9강에서 test_venv2 안에 "Python 3.13 + PySide6" 조합을 완성했습니다.
이제 이 프로젝트를 다른 PC에서 실행해야 한다고 가정해 봅시다.
가장 먼저 떠오르는 방법은 단순합니다 — "가상환경 폴더째 압축해서 옮기면 되지 않을까?" 이번 강의에서는 이 직관적인 방법이 왜 실패하는지 확인하고, 대신 사용하는 올바른 방식인 requirements.txt를 이해합니다.
결론을 미리 요약하면 다음과 같습니다. 가상환경 폴더는 "결과물"이라 옮기지 않고, 그 결과물을 다시 만들 수 있는 "재설치 설명서"인 requirements.txt만 공유합니다.
| 구분 | 내용 |
| 이해할 것 | 소스 코드만 옮기면 부족한 이유, .venv 폴더를 직접 옮기면 안 되는 네 가지 이유 |
| 정리할 것 | 공유할 것(소스 코드 + requirements.txt)과 공유하지 않을 것(.venv)의 구분 기준 |
| 확인할 것 | "가상환경은 옮기는 대상이 아니라 다시 만드는 대상"이라는 원칙 |
1. 문제 상황 — 소스 코드만으로는 부족하다
→ 내 코드를 다른 PC로 옮겼을 때 실행이 실패하는 이유를 확인합니다.
Python 프로젝트는 보통 외부 패키지를 사용합니다.
GUI 화면에는 PySide6가, MySQL 연결에는 mysql-connector-python 같은 패키지가 필요합니다.
작업중인 Python 프로젝트
→ PySide6 사용
→ mysql-connector-python 사용
→ 외부 패키지 필요
그런데 7강에서 확인했듯 패키지의 정체는 site-packages 폴더에 설치된 별도의 폴더입니다.
내가 작성한 main.py 파일 안에 패키지가 들어 있는 것이 아닙니다.
그래서 main.py만 다른 PC로 옮기면 이런 일이 벌어집니다.
기존 PC (9강까지의 환경)
→ main.py 있음
→ test_venv2 안에 PySide6 설치됨
→ 실행 성공
main.py 파일만 새 PC로 복사
↓
새 PC
→ main.py 있음
→ PySide6 없음 ❌
→ ModuleNotFoundError 발생 ← 코드는 그대로인데 실행 실패
8강에서 본 호환성 문제의 재현입니다.
코드가 있다는 것과 실행된다는 것은 다르고, 실행에는 패키지 조합이 함께 준비되어야 합니다.
그렇다면 그 조합을 어떻게 새 PC로 가져갈 것인가 — 이것이 이번 강의의 질문입니다.
2. 왜 .venv 폴더를 통째로 옮기면 안 되는가
→ 가장 직관적인 해결책이 실패하는 네 가지 이유를 확인합니다.
"패키지가 test_venv2 안에 있으니, 그 폴더째 압축해서 옮기면 되지 않을까?" 자연스러운 생각이지만,
이 방법은 네 가지 이유로 권장하지 않습니다.
2.1 이유 1 — 용량이 크다
가상환경 폴더에는 Python 실행 파일, pip 관련 파일, 설치된 패키지 전체가 들어 있습니다.
9강에서 설치한 PySide6처럼 GUI 패키지는 특히 용량이 큽니다.
수백 MB짜리 폴더를 옮기는 것과, 아래에서 볼 몇 줄짜리 텍스트 파일을 옮기는 것 — 결과가 같다면 답은 분명합니다.
.venv
├─ bin
├─ lib
│ └─ python3.x
│ └─ site-packages
│ ├─ PySide6
│ ├─ shiboken6
│ └─ 기타 패키지따라서 .venv 폴더를 그대로 압축해서 공유하면 파일 용량이 불필요하게 커질 수 있습니다.
반면 requirements.txt는 텍스트 파일이기 때문에 용량이 매우 작습니다.
공유 방식특징| .venv 폴더 공유 | 용량이 큼 |
| requirements.txt 공유 | 용량이 작음 |
| 새 환경에서 재설치 | 필요한 패키지만 다시 설치 가능 |
2.2 이유 2 — 내부가 생성 위치의 경로에 묶여 있다
가상환경은 처음 만들어진 위치를 기준으로 동작합니다. 6강에서 확인한 pyvenv.cfg를 떠올려 보세요 — 원본 Python의 절대 경로가 기록되어 있었습니다. 활성화 스크립트 등 내부 파일들도 생성 당시 경로를 기준으로 만들어집니다.
기존 PC
→ /home/basiclike/Project/.venv
새 PC
→ /home/student/NewProject/.venv사용자명이나 폴더 구조가 조금만 달라도 내부 경로가 어긋나 오작동할 수 있습니다. 즉 가상환경은 복사해서 옮기는 대상이 아니라, 새 위치에서 다시 만드는 대상입니다.
2.3 이유 3 — 운영체제마다 구조가 다르다
가상환경의 내부 구조는 OS에 따라 다릅니다. 이 시리즈에서 계속 사용한 활성화 경로가 Windows에서는 아예 다른 위치입니다.
| 운영체제 | 가상환경 실행 파일 위치 |
| Ubuntu / macOS | .venv/bin/python |
| Windows | .venv\Scripts\python.exe |
따라서 Ubuntu에서 만든 가상환경을 Windows로(또는 그 반대로) 그대로 옮기는 것은 구조적으로 동작할 수 없습니다. 협업 상대가 어떤 OS를 쓸지는 알 수 없으므로, OS에 묶인 폴더를 공유하는 방식 자체가 부적합합니다.
2.4 이유 4 — Python 버전이 다르면 동작하지 않는다
가상환경은 특정 Python 버전을 기준으로 만들어집니다.
예를 들어 기존 프로젝트에서 Python 3.13으로 가상환경을 만들었다고 가정합니다.
기존 프로젝트
→ Python 3.13 기반 .venv
그런데 새 PC에는 Python 3.12만 설치되어 있을 수 있습니다.
새 PC
→ Python 3.12만 설치됨이 경우 기존 .venv 폴더를 그대로 옮겨도 정상적으로 동작하지 않을 수 있습니다.
그래서 새 환경에서는 1) Python 버전에 맞게 가상환경을 새로 만들고, 2) requirements.txt를 기준으로 패키지를 다시 설치하는 것이 안전합니다.
3. 올바른 방식 — requirements.txt로 목록만 공유한다
→ 결과물 대신 재설치 설명서를 공유한다는 원칙과 그 동작 방식을 이해합니다.
3.1 requirements.txt란?
네 가지 이유의 공통 결론은 "폴더가 아니라 정보를 옮겨야 한다"입니다.
새 PC에 필요한 정보는 사실 단순합니다 — 어떤 패키지의 어떤 버전이 필요한가?
이 목록을 기록한 텍스트 파일이 requirements.txt입니다.
PySide6==6.7.0
mysql-connector-python==8.4.0
중요한 것은 이 파일이 패키지 기능을 담고 있는 파일이 아니라는 점입니다.
패키지의 이름과 버전, 즉 "필요한 것의 목록"만 적혀 있습니다.
== 뒤의 숫자가 버전 고정입니다 — 8강에서 본 것처럼 버전이 달라지면 동작이 달라질 수 있으므로, 정확한 버전을 기록해 두는 것이 핵심입니다. 이 파일이 있으면 새 환경에서 다음 한 줄로 같은 조합을 다시 설치할 수 있습니다.
python -m pip install -r requirements.txt # -r: 파일에 적힌 목록(requirements)대로 설치
3.2 공유 기준 정리
이제 무엇을 공유하고 무엇을 공유하지 않는지 기준이 섰습니다.
| 항목 | 공유 여부 | 이유 |
| 소스 코드 (main.py 등) | 공유 ⭕ | 직접 작성한 프로그램 — 프로젝트의 본체 |
requirements.txt |
공유 ⭕ | 환경을 다시 만들 수 있는 재설치 설명서 |
.venv / venv 폴더 |
공유 ❌ | 용량·경로·OS·버전에 묶인 결과물 — 새 환경에서 다시 만든다 |
이 방식의 장점은 공유에서 끝나지 않습니다. 환경이 꼬였을 때의 문제 해결 절차도 같은 원리로 단순해집니다. 4강에서 "가상환경은 소모품"이라고 했던 것이 여기서 완성됩니다.
환경에 문제가 생겼을 때
기존 .venv 삭제
→ 새 .venv 생성
→ requirements.txt 기준 재설치
→ 실행 확인 ← 언제든 처음부터 깨끗하게 재구성 가능requirements.txt만 있으면 가상환경은 언제든 버리고 다시 만들 수 있습니다. 결과물(폴더)이 아니라 설명서(목록)를 관리하는 것 — 이것이 Python 프로젝트 공유의 표준 방식입니다.
- 패키지는 소스 코드에 포함되지 않는다 — 코드만 옮기면 ModuleNotFoundError
- .venv는 용량·경로·OS·버전에 묶여 있어 옮기는 대상이 아니다
- 공유하는 것: 소스 코드 + requirements.txt / 공유하지 않는 것: .venv
- 가상환경 = 결과물, requirements.txt = 재설치 설명서
→ 다음 강의 (11강): 이번 강의의 원칙을 터미널에서 실행합니다. 실제 프로젝트 폴더를 만들어 pip freeze로 requirements.txt를 생성하고, 새 폴더에 새 가상환경을 만들어 pip install -r로 같은 조합이 복원되는 것을 확인합니다.