개발 환경 관리 가이드

아래 내용은 팀/회사 개발 환경을 안정적으로 유지하기 위한 환경 관리 모범 사례(Best Practices)를 정리한 가이드입니다.
venv, conda, pyenv, Windows/Mac 환경을 모두 고려해 통합적으로 구성했습니다.

---

환경 관리 모범 사례 가이드

1. 프로젝트마다 독립된 가상환경을 반드시 구성한다

• 프로젝트 간 패키지 충돌을 방지하고 재현성을 높인다.
• venv 또는 conda 중 하나를 선택해 일관되게 사용한다.
• 가상환경 폴더는 보통 .venv/ 또는 env/로 통일한다.

예시:

project/
 ├─ app/
 ├─ .venv/
 ├─ requirements.txt
 ├─ environment.yml
 └─ README.md

---

2. 파이썬 버전과 패키지 버전을 명시적으로 관리한다

• “3.10”만 적지 말고 “3.10.13”처럼 패치 버전까지 고정한다.
• 파이썬 버전은 맥에서는 pyenv, 윈도우에서는 py launcher(py -3.11)로 관리한다.
• 패키지 버전도 가능하면 고정(pip freeze)한다.

예시:

numpy==1.26.4
pandas==2.1.4
fastapi==0.109.0

---

3. pip 요구사항 파일과 conda 환경 파일을 둘 다 제공한다

팀 구성원이 pip만 쓰거나 conda만 사용하는 경우가 있기 때문이다.

• pip 환경 공유
• pip freeze > requirements.txt
• conda 환경 공유
• conda env export --from-history > environment.yml

README.md에 두 설치 방법 모두를 명시한다.

---

4. 시스템 파이썬을 절대 사용하지 않는다

• 시스템 파이썬은 OS와 연결되어 있어 버전 충돌 위험이 있다.
• 항상 전용 파이썬 버전을 설치(pyenv, conda, python.org 등)하고 가상환경을 만든다.

---

5. 가상환경 파일(.venv)은 Git에 포함하지 않는다

• 모두의 운영체제에서 경로 구조가 달라 충돌이 발생한다.
• 대신 requirements.txt 혹은 environment.yml만 공유한다.

.gitignore에는 반드시 다음을 포함한다:

.venv/
env/
__pycache__/
.ipynb_checkpoints/

---

6. PYTHONPATH 오염을 피하고 프로젝트 구조를 표준 패키지 형태로 구성한다

잘못된 실행 위치 때문에 ModuleNotFoundError가 자주 발생한다.

권장 형태:

project/
 ├── app/
 │    ├── __init__.py
 │    ├── main.py
 │    └── workflow/
 │            └── ...
 ├── tests/
 └── run.py

실행은 항상 프로젝트 루트에서:

python -m app.main

---

7. 패키지 설치는 가급적 버전 명시하고, 최신 업데이트는 신중하게 적용한다

• ML 패키지는 minor update에도 API가 깨질 수 있다.
• requirements.txt를 업데이트할 땐 팀원과 조율해야 한다.

추가로 패키지 상태를 검사하려면:

pip list --outdated

---

8. 재현성 보장을 위해 “환경 잠금(lock)”을 사용하는 것도 고려한다

• pipenv, poetry, uv 등은 “lock 파일”로 완전한 버전 고정이 가능하다.
• 팀 규모가 커질수록 추천된다.

예시:

pipenv install
pipenv lock

---

9. 가상환경이 꼬이면 즉시 삭제 후 재생성한다

venv는 가벼우므로 문제가 있으면 다음처럼 재설정한다:

deactivate
rm -rf .venv
python -m venv .venv
pip install -r requirements.txt

conda도 같은 원리:

conda remove -n myenv --all
conda env create -f environment.yml

---

10. 환경을 README.md에 명확하게 문서화한다

예시 템플릿:

# 프로젝트 실행 방법

## 1. Python 버전
Python 3.10.13

## 2. venv 환경 생성
python3 -m venv .venv
source .venv/bin/activate

## 3. 패키지 설치
pip install -r requirements.txt

## 4. 실행
python -m app.main

---

11. 운영체제(Mac/Windows/Linux) 간 차이를 기록한다

예를 들어:

• Mac: source .venv/bin/activate
• Windows PowerShell: .\.venv\Scripts\Activate.ps1
• Windows CMD: .\.venv\Scripts\activate

README에 OS별 예시를 넣어주면 팀원 onboarding 속도가 크게 개선된다.

---

12. Docker와 가상환경을 함께 사용할 때는 “중복 관리”를 피한다

• Dockerfile 내에서 pip 설치를 관리하는 경우
  로컬 venv는 개발용, Docker는 운영용 역할로 분리한다.
• conda + docker는 이미지 용량이 커지므로 필요할 때만 사용한다.

---

13. 중요한 패턴: “하나의 프로젝트 = 하나의 Python 버전 = 하나의 가상환경”

이 원칙만 잘 지켜도 대부분의 환경 문제는 사라진다.

 

개발자 모두 아자아자 화이팅!