10. Python 패키지 공유 이해

0. 학습 목표

이번 단계에서는 Python 프로젝트에서 사용하던 `외부 패키지 목록`을 requirements.txt 파일로 저장하고,

새 환경에서 같은 패키지들을 다시 설치하는 이유를 학습합니다.

 

Python 프로젝트를 다른 PC나 새 폴더에서 실행할 때는

소스 코드뿐만 아니라, 프로젝트에서 사용한 외부 라이브러리도 함께 준비되어야 합니다.

 

하지만 .venv 또는 venv 같은 작업중인 가상환경 폴더를 그대로 압축해서 옮기는 방식은 권장하지 않습니다.

 

대신 현재 가상환경에 설치된 패키지 목록만 requirements.txt 파일로 저장하고,

새 환경에서 그 목록을 기준으로 패키지를 다시 설치하는 방식이 안전합니다.

1. requirements.txt가 필요한 이유

1.1. 파이썬 패키지 특성

Python 프로젝트는 보통 외부 라이브러리를 많이 사용합니다.

 

예를 들어 GUI 프로그램을 만들 때는 PySide6 패키지가 필요할 수 있고,

MySQL 데이터베이스에 연결할 때는 mysql-connector-python 같은 패키지가 필요할 수 있습니다.

작업중인 Python 프로젝트
→ PySide6 사용
→ mysql-connector-python 사용
→ 외부 패키지 필요

하지만 이 패키지들은 Python 파일 안에 자동으로 포함되는 것이 아닙니다.

즉, 내가 만든 main.py 소스코드 파일을 다른 PC로 옮긴다고 해서

작업중에 사용하던 PySide6나 mysql-connector-python 패키지까지 함께 옮겨지는 것은 아닙니다.

 

1.2. 새 PC 작업에서 하려면?

기존 프로젝트 작업환경에는 필요한 패키지가 이미 설치되어 있습니다.

기존 프로젝트 환경
→ PySide6 설치됨
→ mysql-connector-python 설치됨
→ 프로그램 실행 가능

 

하지만 새 PC나 새 폴더와 같은 개발환경에서는 해당 패키지가 없을 수 있습니다.

새 PC 또는 새 폴더
→ PySide6 라이브러리 없음❌
→ mysql-connector-python 라이브러리 없음❌
→ 프로그램 실행 오류 발생 가능

 

1.3. 필요한 패키지 목록을 requirements.txt 파일로 공유

이 문제를 해결하기 위해 기존 프로젝트에 필요한 패키지 목록을 requirements.txt 파일로 저장합니다.

기존 개발환경
→ requirements.txt 생성

새 개발환경
→ requirements.txt 기준으로 패키지 재설치

 requirements.txt 파일에는 프로젝트 실행에 필요한 패키지 이름과 버전 정보가 기록됩니다.

 

1.4. requirements.txt 예시

예를 들어 requirements.txt 파일에 다음과 같은 내용이 들어갈 수 있습니다.

PySide6==6.7.0
mysql-connector-python==8.4.0

즉, requirements.txt는 프로젝트의 외부 패키지 목록을 기록한 파일입니다.

 

이 파일이 있으면 새 PC 환경에서 다음 명령어로 필요한 패키지를 다시 설치할 수 있습니다.

python -m pip install -r requirements.txt

 

 

1.5. requirements.txt 역할

requirements.txt는 패키지 기능을 담고 있는 파일이 아닙니다. 필요한 패키지 목록을 적어 둔 파일입니다.

구분	설명
소스 코드	직접 작성한 Python 파일
외부 패키지	PySide6, mysql-connector-python 같은 설치형 라이브러리
requirements.txt	필요한 외부 패키지 목록
새 가상환경	새 환경에서 다시 만들어 사용하는 독립 실행 환경

소스 코드
→ 내가 작성한 프로그램

requirements.txt
→ 프로그램 실행에 필요한 패키지 목록

새 가상환경
→ requirements.txt를 기준으로 패키지를 다시 설치하는 공간

 

1.6. 패키지 공유 핵심

공유할 것
→ 소스코드(main.py)
→ requirements.txt

공유하지 않을 것
→ .venv
→ venv

2. 가상환경 폴더를 공유하지 않는 이유

2.1.  용량 문제

가상환경 폴더 안에는 Python 실행 파일, pip 관련 파일, 설치된 외부 패키지들이 들어 있습니다.

특히 PySide6 같은 GUI 패키지는 용량이 클 수 있습니다.

.venv
├─ bin
├─ lib
│  └─ python3.x
│     └─ site-packages
│        ├─ PySide6
│        ├─ shiboken6
│        └─ 기타 패키지

따라서 .venv 폴더를 그대로 압축해서 공유하면 파일 용량이 불필요하게 커질 수 있습니다.

반면 requirements.txt는 텍스트 파일이기 때문에 용량이 매우 작습니다.

공유 방식	특징
.venv 폴더 공유	용량이 큼
requirements.txt 공유	용량이 작음
새 환경에서 재설치	필요한 패키지만 다시 설치 가능

 

2.2. 기존 PC의 경로 및 불필요한 정보 유출 가능성

가상환경은 생성된 위치와 연결되어 동작합니다.

예를 들어 기존 PC에서 다음 위치에 가상환경을 만들었다고 가정합니다.

/home/basiclike/Project/.venv

이 가상환경을 다른 PC의 다른 위치로 그대로 옮기면 내부 경로가 맞지 않을 수 있습니다.

기존 PC
→ /home/basiclike/Project/.venv

새 PC
→ /home/student/NewProject/.venv

가상환경 내부의 일부 실행 파일이나 설정은 처음 만들어진 경로를 기준으로 동작할 수 있기 때문에, 단순 복사 후 문제가 생길 수 있습니다.

즉, 가상환경은 복사해서 옮기는 대상이 아니라, 새 프로젝트 위치에서 다시 만드는 대상입니다.

 

2.3. 운영체제마다 가상환경 구조가 다르다

Windows, Ubuntu, macOS는 가상환경 내부 구조가 다릅니다.

예를 들어 Ubuntu에서는 가상환경 활성화 파일이 보통 다음 위치에 있습니다.

source .venv/bin/activate

하지만 Windows에서는 구조가 다릅니다.

.venv\Scripts\activate

운영체제	가상환경 실행 파일 위치 예시
Ubuntu / macOS	.venv/bin/python
Windows	.venv\Scripts\python.exe

따라서 Ubuntu에서 만든 .venv 폴더를 Windows로 그대로 옮기거나, Windows에서 만든 .venv 폴더를 Ubuntu로 그대로 옮기는 방식은 안전하지 않습니다.

 

2.4. Python 버전 차이로 문제가 생길 수 있다

가상환경은 특정 Python 버전을 기준으로 만들어집니다.

예를 들어 기존 프로젝트에서 Python 3.13으로 가상환경을 만들었다고 가정합니다.

기존 프로젝트
→ Python 3.13 기반 .venv

 

그런데 새 PC에는 Python 3.12만 설치되어 있을 수 있습니다.

새 PC
→ Python 3.12만 설치됨

이 경우 기존 .venv 폴더를 그대로 옮겨도 정상적으로 동작하지 않을 수 있습니다.

 

그래서 새 환경에서는 1) Python 버전에 맞게 가상환경을 새로 만들고, 2) requirements.txt를 기준으로 패키지를 다시 설치하는 것이 안전합니다.

 

2.5. 패키지 정리와 문제 해결이 복잡해질 수 있다

가상환경 폴더를 그대로 공유하면, 어떤 패키지가 왜 설치되어 있는지 파악하기 어려울 수 있습니다.

반면 requirements.txt를 사용하면 프로젝트에 필요한 패키지 목록을 텍스트로 확인할 수 있습니다.

requirements.txt
→ PySide6==6.7.0
→ mysql-connector-python==8.4.0

또한 문제가 생겼을 때도 다음 순서로 다시 정리할 수 있습니다.

기존 .venv 삭제
→ 새 .venv 생성
→ requirements.txt 기준 재설치
→ 실행 확인

이 방식은 가상환경을 직접 옮기는 방식보다 관리하기 쉽습니다.

 

2.6. 안전한 공유 방식

Python 프로젝트를 공유할 때는 다음과 같이 생각하면 됩니다.

가상환경 폴더는 결과물
requirements.txt는 재설치 설명서

 

즉, .venv 폴더 자체를 공유하는 것이 아니라,

새 환경에서 .venv를 다시 만들 수 있도록 필요한 패키지 목록을 공유하는 것입니다.

항목	공유 여부	이유
main.py	공유	직접 작성한 소스 코드
.ui 파일	공유	화면 설계 파일
이미지 파일	공유	프로그램 실행에 필요한 리소스
requirements.txt	공유	필요한 패키지 목록
.venv	공유하지 않음	용량, 경로, OS, Python 버전 문제 가능
venv	공유하지 않음	새 환경에서 다시 만드는 것이 안전

 

2.7. 핵심

권장하지 않음
→ .venv 폴더 압축
→ 다른 PC에 복사
→ 그대로 실행 시도

권장 방식
→ requirements.txt 공유
→ 새 PC에서 .venv 새로 생성
→ python -m pip install -r requirements.txt (공유된 패키지 목록 설치)
→ 실행 확인