개발환경의 중요성

성주(Seongju)·2025년 11월 26일

docker python venv 개발환경 환경설정

학습

목록 보기

3/6

여러 대회랑 프로젝트를 동시에 하다 보니
어느 순간부터 “코드를 못 짜서 막히는 게 아니라, 환경 때문에 멈추는 시간”이 점점 늘어나기 시작했다.

대회 제출용 코드
수업/과제용 실습 코드
Colab / 로컬 / 서버 환경

이렇게 서로 다른 코드들을 왔다 갔다 하다 보니,
Python 버전, 패키지 버전, 플랫폼 차이가 한 번 꼬이면
그날은 그냥 환경만 붙잡고 끝나는 날이 많았다.

이번 글에서는 최근에 겪었던 환경 관련 문제들을 간단히 정리하고,
그걸 계기로 Python 버전 / venv / Docker를 같이 공부해야겠다고 마음먹게 된 이유를 기록해 두려고 한다.

1. 코드는 맞는데, 실행이 안 되는 상황들

최근 몇 달 동안 공통적으로 반복됐던 패턴은 대략 이렇다.

깃허브나 예제 레포를 하나 받아온다.
pip install로 필요한 패키지를 깐다.
그때는 잘 돈다.
시간이 지나서 다시 실행해보면, 똑같은 코드인데도 에러가 난다.

주된 원인은 대부분 환경 쪽이었다.

torch, transformers, ultralytics, opencv 같은 패키지 버전 충돌
Colab에서는 돌아가는데, 로컬에서는 ModuleNotFoundError, ImportError
GPU를 쓰고 싶은데 CUDA / 드라이버 / Torch 버전이 안 맞아서 결국 CPU로만 돌리는 상황

문제 자체는 구글링하면 어떻게든 풀린다.
하지만 매번 패키지 삭제 → 재설치 → 버전 조정을 반복하다 보니,
정작 모델을 개선하거나 실험을 더 해볼 시간과 집중력이 계속 깎이는 느낌이었다.

2. Python 버전과 전역 pip의 한계

처음에는 그냥 “최신 Python 쓰면 되지”라는 생각이었다.
로컬에 최신 Python을 깔아두고, 전역 환경에 pip install로 계속 쌓아 올렸다.

시간이 지나면서 이런 상황이 생겼다.

어떤 프로젝트는 Python 3.11 기준으로 잘 돌아가고
어떤 라이브러리는 3.11까지만 안정적으로 지원하고
Colab / 로컬 / 과제 베이스 코드마다 요구하는 버전이 제각각이고
전역에 깔린 패키지들이 서로 영향을 주면서
“어디서부터 잘못됐는지 감이 안 오는 상태”가 됐다.

결국, 처음부터 환경을 분리하지 않고 쓰다가
나중에 커진 대가를 한 번에 맞는 느낌이었다.

그래서 앞으로는:

프로젝트를 시작할 때 Python 버전을 먼저 정하고,
전역 환경이 아니라 프로젝트별 가상환경(venv)을 기본으로 쓰기로 했다.

3. venv를 기본값으로 두기로 한 이유

지금 기준으로 가져가고 싶은 기본 템플릿은 아주 단순하다.

# 1) 프로젝트 폴더 진입
cd my-project

# 2) Python 버전 명시 (예: 3.11)
python3.11 -m venv .venv

# 3) 가상환경 활성화
# Windows: .venv\Scripts\activate
source .venv/bin/activate

# 4) 패키지 설치
pip install -r requirements.txt   # 또는 개별 설치 후
pip freeze > requirements.txt     # 의존성 기록

이렇게 하면:

프로젝트마다 환경이 분리되고
requirements.txt만 있으면 시간이 지나도 환경을 다시 구성할 수 있고
다른 프로젝트가 패키지를 덮어써서 깨뜨리는 상황을 줄일 수 있다.

특히 “몇 달 뒤에 다시 열어볼 프로젝트”일수록
코드 + venv + requirements 조합으로 정리해 두는 게 훨씬 안전하다는 걸 느꼈다.

4. Docker를 공부해야겠다고 느낀 지점

venv만 써도 많이 나아지긴 한다.
그래도 여전히 애매하게 남는 부분이 있다.

Windows / Linux처럼 OS가 달라질 때 미묘하게 달라지는 동작
팀 프로젝트에서 “내 환경에서는 되는데, 다른 사람 환경에서는 안 되는” 상황
Colab / 로컬 / 서버 환경이 서로 달라서 재현성이 흔들리는 문제

이런 것들을 한 번에 줄이려면,
결국 환경 전체를 컨테이너로 묶는 쪽(Docker)이 자연스러운 해답 같다는 생각이 들었다.

아직 Docker를 자유롭게 쓰는 단계는 아니지만,
일단은 이런 정도의 구조를 목표로 잡고 있다.

FROM python:3.11

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "main.py"]

장기적으로는:

대회용 코드나 포트폴리오용 서비스
팀 프로젝트에서 공유해야 할 코드

이런 것들은 가능하면 Docker 기준으로도 한 번 정리해 두는 것을 목표로 삼고 있다.

5. 앞으로의 개발환경에 대한 정리

이번 학기/올해를 지나면서,
개발환경에 대해 최소한 아래 네 가지는 지키려고 한다.

Python 버전 명시
- 프로젝트 시작 시 3.10 / 3.11 중 하나로 고정
- 사용하는 라이브러리가 안정적으로 지원하는 버전을 기준으로 선택
프로젝트별 venv 필수
- 전역 pip 최소화
- .venv + requirements.txt를 기본 셋업으로 사용
중요한 프로젝트는 Docker도 함께 고려
- “다른 환경에서도 반드시 돌아가야 하는 코드”는
  Docker 컨테이너 기준으로 한 번 더 정리
환경 복구 방법을 기록으로 남기기
- “새 환경에서 이 프로젝트를 어떻게 다시 실행할 수 있는지”를
  README나 블로그에 같이 적어 두기