Ch 04. 노트북 재현성 검증과 공유 — 실전 marimo

노트북 재현성 검증과 공유

노트북이 완성됐습니다. 이제 중요한 질문을 던져야 합니다. "다른 사람이 이 노트북을 실행하면 나와 같은 결과를 얻을까?"

연구자에게 이 질문은 핵심입니다. 분석 결과를 논문에 쓰거나 보고서에 담을 때, 동료가 같은 노트북을 실행해 같은 숫자를 보는 것이 신뢰의 기반입니다. "내 컴퓨터에서는 됐는데"는 연구에서 통하지 않습니다.

이 챕터는 이 프로젝트 노트북이 왜 재현 가능한지를 분석하고, 그 재현성을 외부에서 검증하는 방법을 다룹니다. 그리고 노트북을 다른 사람과 공유하는 실제 워크플로우를 정리합니다.

재현성의 세 가지 층

이 노트북의 재현성은 세 가지 층에서 보장됩니다.

첫 번째는 데이터 재현성입니다. 셀 2에서 np.random.default_rng(42)로 데이터를 생성했습니다. 난수 시드가 고정되어 있어 몇 번을 실행해도 동일한 500행 데이터프레임이 만들어집니다. 외부 파일이나 API에 의존하지 않습니다. 인터넷이 없어도, 파일 경로가 달라도 동일한 데이터입니다.

두 번째는 실행 재현성입니다. marimo는 변수 단일 정의 규칙을 강제합니다. df는 셀 2에서만 정의되고, 나머지 셀은 df를 읽기만 합니다. Jupyter에서 발생하는 hidden state 문제가 없습니다. 셀 실행 순서에 관계없이 DAG가 결정론적으로 실행 순서를 결정합니다. 처음 실행하든 열 번 실행하든 같은 순서로 같은 결과를 냅니다.

세 번째는 환경 재현성입니다. 파이썬 버전과 라이브러리 버전이 다르면 같은 코드도 다른 결과를 낼 수 있습니다. 이 층은 노트북 외부에서 관리해야 합니다. 아래에서 두 가지 방법을 다룹니다.

marimo check로 노트북 정적 검증

공유하기 전에 노트북에 구조적 문제가 없는지 확인합니다. marimo check는 노트북 파일을 실행하지 않고 정적 분석만 합니다. 순환 의존성, 변수 중복 정의 같은 문제를 찾아냅니다.

marimo check eda_project.py

문제가 없으면 아무 출력이 없거나 통과 메시지를 표시합니다. 문제가 있으면 어떤 셀에서 무슨 에러가 발생했는지 알려줍니다.

(예시 — 문제가 없는 경우)All checks passed.

PART 05 Ch 05에서 살펴본 것처럼 marimo check를 CI 파이프라인에 넣을 수도 있습니다. 팀 저장소에서 노트북을 수정할 때마다 자동으로 검증이 돌아갑니다.

의존성 고정: requirements.txt

노트북이 사용하는 라이브러리 버전을 고정합니다. 가장 간단한 방법은 requirements.txt입니다.

marimo==0.23.0numpy==2.0.0pandas==2.2.2plotly==5.22.0

위 버전은 예시입니다. 실제로는 pip freeze | grep -E "marimo|numpy|pandas|plotly"로 본인 환경의 설치 버전을 확인해 기입합니다. 이 파일을 노트북과 같은 디렉터리에 두고 git에 커밋합니다. 다른 사람이 이 노트북을 받았을 때 실행하는 명령은 이렇습니다.

pip install -r requirements.txtmarimo edit eda_project.py

버전이 정확히 고정되어 있으면 동일한 환경이 구성됩니다.

의존성 고정: PEP 723 인라인 메타데이터

marimo는 노트북 파일 안에 의존성을 기록하는 PEP 723 인라인 메타데이터를 지원합니다. --sandbox 옵션으로 노트북을 실행하면 marimo가 자동으로 격리 가상환경을 만들고 의존성을 설치합니다.

marimo edit --sandbox eda_project.py

에디터에서 패키지를 설치하면 노트북 파일 상단에 메타데이터가 자동으로 기록됩니다. 결과는 이런 형태입니다.

# /// script# requires-python = ">=3.11"# dependencies = [#     "marimo==0.23.0",#     "numpy==2.0.0",#     "pandas==2.2.2",#     "plotly==5.22.0",# ]# ///import marimo__generated_with = "0.23.0"app = marimo.App()

requirements.txt가 없어도 노트북 파일 하나에 의존성 정보가 담깁니다. 이 파일을 받은 사람이 --sandbox로 실행하면 의존성이 자동으로 설치되고 격리 환경에서 노트북이 열립니다.

두 방법 중 어느 것을 쓸지는 팀의 관습이나 배포 환경에 따라 결정합니다. 중요한 것은 방법을 선택하고 일관되게 적용하는 것입니다.

노트북 파일과 git

marimo 노트북은 순수 Python .py 파일입니다. git에서 아무 처리 없이 버전 관리가 됩니다.

노트북과 의존성 파일을 함께 커밋합니다.

git add eda_project.py requirements.txtgit commit -m "feat: EDA 노트북 완성 — 합성 데이터 기반 재현 가능 분석"

git diff로 변경 내용을 확인하면 JSON 덩어리가 아니라 Python 코드 변경만 보입니다.

git diff eda_project.py

(예시 출력)@@ -45,6 +45,9 @@ def _():+    fig_weekday = px.line(+        weekday_pd,+        x="weekday",

코드 줄 단위 diff입니다. 무엇이 바뀌었는지 바로 읽을 수 있습니다. PR 리뷰도 명확해집니다.

노트북 전체 실행 검증

공유 전에 노트북 전체가 오류 없이 실행되는지 확인합니다. marimo 노트북은 일반 Python 스크립트처럼 직접 실행할 수 있습니다.

python eda_project.py

에디터 없이 커맨드라인에서 실행됩니다. 오류가 있으면 어느 셀에서 발생했는지 표준 오류 메시지로 알 수 있습니다. CI에서 이 명령을 실행해 노트북 전체를 검증하는 방법은 PART 10에서 자세히 다룹니다.

재현성 점검표

노트북을 공유하기 전에 아래 항목을 확인합니다.

[ ] 데이터 생성에 고정 시드를 사용했는가? (np.random.default_rng(42))[ ] 외부 파일이나 네트워크 의존이 없는가?[ ] 동일 변수를 두 개 이상의 셀에서 정의하지 않았는가? (MB002)[ ] marimo check를 통과했는가?[ ] requirements.txt 또는 PEP 723 메타데이터로 버전을 고정했는가?[ ] python eda_project.py 실행이 오류 없이 완료되는가?[ ] eda_project.py와 의존성 파일을 git에 커밋했는가?

이 목록을 통과한 노트북은 누구에게 보내도 같은 결과를 낼 수 있는 상태입니다.

완성된 프로젝트 구조

eda_project/├── eda_project.py       # marimo 노트북 (순수 Python)└── requirements.txt     # 의존성 버전 고정

간결합니다. 출력 파일, 중간 데이터 파일, 설정 파일이 없습니다. 노트북 하나와 의존성 목록 하나로 전체 분석이 재현됩니다.

정리

이 노트북의 재현성은 세 층에서 보장됩니다. 고정 시드(데이터), 변수 단일 정의와 결정론적 DAG(실행), 버전 고정(환경)입니다.
marimo check eda_project.py로 노트북의 구조적 문제를 실행 없이 검증합니다.
requirements.txt는 간단한 버전 고정 방법입니다. --sandbox와 PEP 723 인라인 메타데이터는 파일 하나로 환경 재현까지 처리합니다.
marimo .py 파일은 git에서 코드 줄 단위 diff가 동작해 변경 이력이 명확합니다.
python eda_project.py로 에디터 없이 전체 노트북을 실행해 최종 검증합니다.