P2-7.5 의존성(dependency)과 재현성(reproducibility)¶

Section ID: P2-7.5 Version: v2026.07.20

P2-7.4에서는 가상환경(virtual environment)과 패키지(package)를 봤습니다. 이제 한 가지 질문이 남습니다.

패키지를 설치하면 끝일까요?

그렇게 보일 수 있습니다. 하지만 학습 코드가 조금만 길어져도 다음 문제가 생깁니다.

내 컴퓨터에서는 실행된다.
다른 사람 컴퓨터에서는 실행되지 않는다.
어제는 실행됐다.
오늘은 패키지 버전이 달라져 결과가 달라졌다.
Colab에서는 된다.
로컬 PC에서는 안 된다.

이 문제는 코드 자체보다 실행 환경을 다시 만들 수 있는가와 관련됩니다. 그래서 의존성(dependency)과 재현성(reproducibility)을 따로 봐야 합니다.

여기서는 의존성(dependency), 재현성(reproducibility), requirements.txt, 버전 고정(version pinning)의 기본 구분을 설명합니다. 뒤에서 예제 프로젝트나 협업 환경을 다시 보더라도, 코드 외에 무엇을 함께 기록해야 하는지는 여기 설명을 기준으로 다시 연결합니다.

여기서는 Python 패키지 배포 체계를 깊게 배우기보다, 같은 코드를 나중에 다시 실행하려면 무엇을 함께 기록해야 하는지 이해하는 데 집중합니다. 여기서 의존성, requirements 파일, 버전 기록의 역할을 잡아 두면, 뒤에서 팀 협업이나 장기 실습을 할 때 코드만 있으면 충분한가를 더 정확하게 판단할 수 있습니다.

지금 이 절에서 잡을 것	바로 다음에 이어질 질문	이후 다시 쓰이는 위치
의존성과 재현성이 코드와 별도 관리 대상이라는 점	P2-7.9에서 실제 로컬 환경 점검 순서로 이어집니다.	이후 모든 실습과 팀 공유 환경에서 다시 씁니다.
`requirements.txt`와 버전 기록의 역할	운영체제별 설치와 Python 버전 점검 질문으로 넘어갑니다.	Part 3 이후 예제 재실행, 프로젝트 전달, 협업 환경 안내에서 반복됩니다.
Colab에서도 재현성 문제가 사라지지 않는다는 점	로컬/클라우드 환경 차이를 비교하는 기준으로 이어집니다.	장기 실험, 리포트 재실행, Part 6 프로젝트 검증에서 바탕이 됩니다.

용어	이 절에서 먼저 잡을 뜻
의존성(dependency)	내 코드가 기대고 있는 외부 패키지와 실행 조건입니다.
재현성(reproducibility)	같은 코드를 나중에 다시 실행할 수 있게 조건을 남기는 성질입니다.
`requirements.txt`	필요한 패키지 목록과 버전을 기록하는 대표 파일입니다.
버전 고정(version pinning)	특정 패키지 버전을 명시해 환경 차이를 줄이려는 방법입니다.
환경 기록(environment record)	Python 버전, 패키지 목록, 실행 위치처럼 재실행에 필요한 메모입니다.

핵심 기준: 의존성(dependency)과 재현성(reproducibility)¶

의존성(dependency)을 내 코드가 실행되기 위해 필요한 외부 패키지로 설명할 수 있습니다.
재현성(reproducibility)을 같은 코드를 나중에 다시 실행할 수 있는 조건으로 설명할 수 있습니다.
requirements.txt가 설치할 패키지 목록을 담는 파일이라는 점을 설명할 수 있습니다.
버전 고정(version pinning)의 필요성과 한계를 입문 수준에서 설명할 수 있습니다.
“내 컴퓨터에서는 된다”가 충분한 설명이 아님을 이해할 수 있습니다.

세 가지 기준¶

기준	왜 중요한가	이 절에서 필요한 이해 수준
의존성은 코드가 기대고 있는 외부 패키지와 실행 조건이다	코드만 보고는 실행되지 않는 이유를 설명해 준다	`import`가 보이면 어떤 외부 패키지가 필요한지 연결할 수 있다
재현성은 같은 코드를 나중에 다시 실행할 수 있게 조건을 남기는 일이다	학습과 협업은 한 번 실행되고 끝나지 않기 때문이다	코드 외에 환경 조건도 함께 남겨야 한다고 이해한다
requirements 파일은 필요한 패키지 목록과 버전 범위를 기록한다	다른 사람이 환경을 다시 만들 때 출발점이 된다	`requirements.txt`의 역할을 한 문장으로 설명할 수 있다

의존성은 내 코드가 기대고 있는 외부 조건이다¶

의존성(dependency)은 내 코드가 실행되기 위해 필요로 하는 외부 조건입니다. Python 실습에서는 주로 패키지 의존성을 먼저 만납니다.

예를 들어 다음 코드는 NumPy가 필요합니다.

문제 상황: 코드가 어떤 외부 패키지에 의존하는지 가장 단순한 예로 확인합니다. 입력(input): NumPy 배열을 만들고 평균을 출력하는 코드입니다. 기대 출력(output): NumPy가 설치되어 있으면 평균값 2.0이 출력됩니다. 확인할 개념: import numpy as np가 보이면 이 코드는 NumPy 패키지에 의존한다는 점을 봅니다.

# 재현 가능한 실행 환경에서 NumPy와 Pandas 예제를 실행하기 위해 필요한 패키지를 불러오는 예제입니다.
import numpy as np

# values는 NumPy 설치와 평균 계산이 모두 되는지 확인할 작은 배열입니다.
values = np.array([1, 2, 3])
print(values.mean())

이 코드는 Python만 있으면 충분하지 않습니다. NumPy가 설치되어 있어야 합니다.

내 코드: import numpy as np를 사용합니다.
필요한 외부 패키지: NumPy입니다.
따라서 NumPy는 이 코드의 의존성입니다.

의존성은 직접 의존성과 간접 의존성으로 나눠 볼 수 있습니다.

직접 의존성: 내가 코드에서 직접 사용하는 패키지입니다.
간접 의존성: 내가 설치한 패키지가 내부적으로 필요로 하는 다른 패키지입니다.

이 구조를 모두 외울 필요는 없습니다. 다만 “내가 설치한 하나의 패키지 뒤에 여러 패키지가 함께 따라올 수 있다”는 감각은 필요합니다.

예시: 같은 코드인데 어떤 곳에서는 실패한다¶

다음 상황을 생각해 봅니다. 책의 예제를 내려받아 평균을 계산하는 Python 파일을 실행했습니다.

문제 상황: 같은 평균 계산 코드가 Colab에서는 되지만 로컬 PC에서는 패키지 부족으로 실패할 수 있음을 봅니다. 입력(input): NumPy 배열로 평균을 계산하는 짧은 코드입니다. 기대 출력(output): NumPy가 준비된 환경에서는 평균이 출력되지만, 없는 환경에서는 import 단계에서 실패할 수 있습니다. 확인할 개념: 코드 문제와 실행 환경 문제를 나누어 봐야 한다는 점을 확인합니다.

# 재현 가능한 실행 환경에서 NumPy와 Pandas 예제를 실행하기 위해 필요한 패키지를 불러오는 예제입니다.
import numpy as np

# scores는 예제 환경에서 평균을 계산할 점수 데이터입니다.
scores = np.array([82, 91, 77, 88])
print(scores.mean())

Colab에서는 실행됩니다. 그런데 로컬 PC 터미널에서는 다음과 비슷한 오류가 날 수 있습니다.

1	`ModuleNotFoundError: No module named 'numpy'`

이 오류는 코드의 평균 계산이 틀렸다는 뜻이 아닙니다. 현재 Python 환경에 NumPy가 준비되어 있지 않다는 뜻입니다.

이때 문제를 다음처럼 나눠 보면 원인을 찾기 쉽습니다.

코드가 요구하는 것: NumPy
현재 환경에 없는 것: NumPy 패키지
해결 방향: 현재 사용 중인 Python 환경에 NumPy를 설치하거나, 필요한 패키지 목록을 보고 환경을 다시 만든다

그래서 패키지를 설치했다는 기억만으로는 부족합니다. 어느 환경에, 어떤 패키지를, 어떤 버전으로 설치했는지 남겨야 합니다.

재현성은 나중에 다시 실행할 수 있는 조건이다¶

재현성(reproducibility)은 같은 코드와 같은 조건에서 다시 실행했을 때, 같은 동작을 기대할 수 있는 성질입니다.

AI와 데이터 실습에서 재현성은 중요합니다. 수학 설명을 읽는 단계에서는 큰 문제가 없어 보이지만, 코드를 실행하는 순간 환경 차이가 결과를 바꿀 수 있습니다.

Python 버전이 다를 수 있습니다.
패키지 버전이 다를 수 있습니다.
운영체제가 다를 수 있습니다.
데이터 파일 위치가 다를 수 있습니다.
Colab 런타임이 초기화되었을 수 있습니다.

따라서 실습을 공유하려면 코드만 주는 것으로는 부족할 수 있습니다. “어떤 환경에서 실행했는가”를 함께 남겨야 합니다.

예시: 학습 노트북을 한 달 뒤 다시 열었을 때¶

AI 학습에서는 “오늘 실행한 노트북”을 한 달 뒤 다시 열어보는 일이 자주 생깁니다.

실행한 날에는 다음 조건이 맞아 있었습니다.

Colab 런타임이 켜져 있었습니다.
numpy, pandas, matplotlib이 이미 설치되어 있었습니다.
데이터 파일을 /content/data/ 폴더에 올려 두었습니다.
코드 셀을 위에서부터 차례대로 실행했습니다.

한 달 뒤에는 상황이 달라질 수 있습니다.

Colab 런타임이 초기화되어 직접 설치한 패키지가 사라졌습니다.
데이터 파일을 다시 업로드하지 않았습니다.
중간 셀부터 실행해서 앞에서 만든 변수가 없습니다.
패키지 기본 버전이 바뀌었습니다.

이때 “코드가 틀렸다”고 바로 판단하면 원인을 놓칠 수 있습니다. 먼저 실행 조건이 다시 만들어졌는지 확인해야 합니다. 재현성은 이 확인을 쉽게 만드는 기록 습관입니다.

requirements 파일은 설치 목록을 남기는 방법이다¶

pip 문서는 requirements files를 pip install에 전달할 설치 항목 목록을 담은 파일로 설명합니다. 흔히 requirements.txt라는 이름을 사용합니다.

예를 들어 다음과 같은 파일을 만들 수 있습니다.

1
2
3

numpy
pandas
matplotlib

그리고 다음처럼 설치할 수 있습니다.

python -m pip install -r requirements.txt

여기서는 이렇게 이해합니다.

requirements.txt는 Python 코드가 아닙니다.
터미널 명령도 아닙니다.
설치해야 할 패키지 목록을 적어 둔 파일입니다.

이 파일이 있으면 다른 사람은 “이 프로젝트가 어떤 패키지를 요구하는가”를 더 쉽게 알 수 있습니다.

예시: 작은 실습 폴더를 다른 사람에게 전달한다¶

작은 실습 폴더가 다음처럼 구성되어 있다고 가정합니다.

score-summary/
  summary.py
  scores.csv
  requirements.txt

summary.py는 CSV 파일을 읽고 평균을 계산합니다.

문제 상황: 다른 사람에게 전달할 작은 실습 코드가 어떤 패키지를 필요로 하는지 확인합니다. 입력(input): pandas로 CSV를 읽고 평균을 계산하는 스크립트입니다. 기대 출력(output): 필요한 환경이 준비되면 점수 평균이 출력됩니다. 확인할 개념: 코드만 전달하면 필요한 패키지를 알기 어려워서 requirements 파일이 함께 필요하다는 점을 봅니다.

# 재현 가능한 실행 환경에서 NumPy와 Pandas 예제를 실행하기 위해 필요한 패키지를 불러오는 예제입니다.
import pandas as pd

# scores.csv를 읽어 표 데이터의 score 열 평균을 계산합니다.
scores = pd.read_csv("scores.csv")
print(scores["score"].mean())

이 파일만 전달하면 받는 사람은 pandas가 필요한지 바로 알기 어렵습니다. 그래서 requirements.txt에 필요한 패키지를 적습니다.

pandas

받는 사람은 폴더로 이동한 뒤 다음 명령으로 필요한 패키지를 준비할 수 있습니다.

python -m pip install -r requirements.txt

이 예시에서 중요한 점은 requirements.txt가 코드를 실행하는 파일이 아니라는 것입니다. 코드가 기대는 외부 패키지 목록을 남기는 파일입니다.

버전을 고정한다는 것은 범위를 좁히는 일이다¶

패키지는 시간이 지나며 바뀝니다. 오늘 설치한 NumPy와 1년 뒤 설치한 NumPy가 같은 버전이라는 보장은 없습니다.

그래서 버전을 적어 둘 수 있습니다.

1
2
3

numpy==2.0.0
pandas==2.2.2
matplotlib==3.9.0

==는 특정 버전을 지정한다는 뜻입니다. 이런 방식을 버전 고정(version pinning)이라고 부를 수 있습니다.

pip 사용자 가이드는 pip freeze 결과를 requirements 파일에 담아 반복 가능한 설치(repeatable installs)에 사용할 수 있다고 설명합니다. 이때 파일에는 pip freeze를 실행한 시점에 설치되어 있던 패키지와 버전이 기록됩니다.

예를 들어 다음 명령을 만날 수 있습니다.

python -m pip freeze > requirements.txt

그리고 다른 환경에서 다음처럼 설치할 수 있습니다.

python -m pip install -r requirements.txt

하지만 버전을 고정한다고 모든 문제가 사라지는 것은 아닙니다. 운영체제, Python 버전, 하드웨어, 패키지 배포 상태가 영향을 줄 수 있습니다. 여기서는 이를 재현성을 높이는 출발점으로 이해합니다.

예를 들어 학습 자료를 만들 때는 다음 두 방식의 차이를 생각할 수 있습니다.

pandas: 최신 버전이 설치될 수 있으므로 시간이 지나면 환경이 달라질 수 있습니다.
pandas==2.2.2: 특정 버전을 요구하므로 당시 환경에 더 가깝게 맞출 수 있습니다.

처음 공부할 때는 모든 패키지를 엄격하게 고정하지 않아도 됩니다. 다만 책의 예제, 수업 자료, 팀 프로젝트처럼 다른 사람이 다시 실행해야 하는 코드라면 버전 기록의 중요성이 커집니다.

requirements 파일과 프로젝트 설정 파일은 역할이 다르다¶

Python Packaging User Guide는 requirements 파일과 패키지의 설치 요구사항을 구분합니다. 여기서는 다음 차이를 기억할 만합니다.

requirements 파일: 특정 환경을 구성하기 위해 설치할 목록입니다.
프로젝트 설정 파일: 패키지를 배포하거나 프로젝트 메타데이터를 설명하는 파일입니다.

이 파트의 실습에서는 복잡한 패키지 배포 구조를 다루지 않습니다. 따라서 requirements.txt를 “실습 환경을 다시 만들기 위한 설치 목록”으로 이해합니다.

Colab에서도 재현성은 사라지지 않는다¶

Colab은 시작이 쉽습니다. 하지만 재현성 문제가 사라지는 것은 아닙니다.

Colab 런타임은 초기화될 수 있습니다. 그때 설치했던 패키지는 사라질 수 있습니다. 또 Colab이 제공하는 기본 패키지 버전이 시간이 지나 바뀔 수도 있습니다.

그래서 노트북 상단에 필요한 설치 명령을 남기거나, 어떤 환경에서 실행했는지 기록하는 습관이 필요합니다.

문제 상황: Colab 노트북을 다시 열었을 때 필요한 패키지를 먼저 다시 준비할 수 있게 합니다. 입력(input): NumPy, pandas, matplotlib 설치를 위한 %pip 명령입니다. 기대 출력(output): 현재 Colab 런타임에 세 패키지가 설치됩니다. 확인할 개념: Colab에서도 재현성을 높이려면 필요한 설치 명령과 환경 메모를 함께 남겨야 한다는 점을 봅니다.

# 노트북 재현에 필요한 주요 패키지를 현재 코드 셀 환경에 설치합니다.
%pip install numpy pandas matplotlib

이 명령은 편리하지만, 장기적으로는 패키지 버전과 실행 날짜를 함께 남기는 편이 더 안전합니다.

예를 들어 노트북 맨 위에 다음처럼 짧은 메모를 둘 수 있습니다.

작성일: 2026-07-20
실행 환경: Google Colab
주요 패키지: numpy, pandas, matplotlib
다시 실행할 때 확인할 것: 런타임 초기화 여부, 데이터 파일 업로드 여부

이 정도의 메모만 있어도 나중에 같은 오류를 반복해서 추적하는 시간을 줄일 수 있습니다.

실습 프로젝트에서 남겨야 할 최소 정보¶

완벽한 재현 환경을 한 번에 만들 필요는 없습니다. 하지만 다음 정보는 남기는 습관이 좋습니다.

어떤 Python 버전에서 실행했는가
어떤 패키지가 필요한가
중요한 패키지의 버전은 무엇인가
코드는 어느 폴더를 기준으로 실행하는가
데이터 파일은 어디에 있어야 하는가
Colab인지 로컬 PC인지

이 정보가 있으면 나중에 오류가 생겼을 때 원인을 좁히기 쉽습니다.

사례 및 예시¶

사례 1. 한 달 뒤 다시 연 노트북이 왜 갑자기 안 되는가¶

한 학습자가 지난달에 잘 실행했던 데이터 분석 노트북을 다시 열었다고 하겠습니다. 당시에는 그래프도 잘 나왔고 CSV도 읽혔는데, 이번에는 패키지 오류와 파일 경로 오류가 함께 납니다.

사람은 쉽게 노트북 파일이 망가졌나라고 생각할 수 있습니다. 하지만 실제로는 Colab 런타임이 초기화되었거나, 패키지 버전이 바뀌었거나, 데이터 파일 위치가 달라졌을 가능성이 더 큽니다. 즉 코드 자체보다 실행 조건이 재현되지 않은 문제입니다.

이 절에서 말하는 의존성, 재현성, requirements.txt, 버전 고정은 이런 실패를 줄이기 위한 장치입니다. 코드를 다시 실행할 수 있으려면 어떤 패키지와 어떤 버전을 기대했는지 함께 남겨야 합니다.

확인 가능한 결과는 설치 목록과 버전 기록이 있는지로 판단할 수 있습니다. requirements.txt 없이 패키지를 기억에만 의존했다면 재현성이 약한 상태이고, 반대로 필요한 패키지와 버전이 기록돼 있다면 같은 환경을 다시 만드는 출발점이 생깁니다.

체크리스트¶

의존성(dependency)을 내 코드가 실행되기 위해 필요한 외부 패키지로 설명할 수 있다.
재현성(reproducibility)을 같은 코드를 나중에 다시 실행할 수 있는 조건으로 설명할 수 있다.
requirements.txt가 설치할 패키지 목록을 담는 파일이라는 점을 설명할 수 있다.
python -m pip install -r requirements.txt가 requirements 파일을 기준으로 패키지를 설치하는 명령임을 설명할 수 있다.
pip freeze가 현재 환경에 설치된 패키지와 버전을 기록하는 데 쓰일 수 있음을 설명할 수 있다.
버전 고정이 재현성을 높일 수 있지만 모든 문제를 해결하지는 않는다는 점을 설명할 수 있다.
이 코드는 어떤 외부 패키지에 기대고 있는가, 그 패키지는 어떤 Python 환경에 설치되어 있는가, 나중에 같은 환경을 다시 만들 수 있는 기록이 있는가를 점검할 수 있다.

출처와 참고 자료¶

Python Packaging Authority, User Guide, pip documentation v26.1.2, 확인 날짜: 2026-07-20. python -m pip, 패키지 설치, requirements 파일, repeatable installs를 위한 pip freeze 사용 맥락 확인에 사용했다.
Python Packaging Authority, pip freeze, pip documentation v26.1.2, 확인 날짜: 2026-07-20. 현재 환경에 설치된 패키지 목록을 requirements 형식으로 출력한다는 설명 확인에 사용했다.
Python Packaging Authority, install_requires vs requirements files, Python Packaging User Guide, 확인 날짜: 2026-07-20. 프로젝트 배포용 의존성 메타데이터와 실행 환경 재현을 위한 requirements 파일의 역할 차이 확인에 사용했다.