Jupyter 노트북이 .py로 저장된다는 게 왜 중요한가

Jupyter notebook을 git에 커밋해본 사람이라면 한 번쯤 같은 생각을 했을 거예요. 이 JSON에 base64로 박힌 이미지 blob 덩어리를 git diff에 올려놓고 코드 리뷰가 진심으로 가능하다고 믿는 사람이 있나.

다들 그냥 nbstripout 깔고, jupytext 써가면서 어찌어찌 살아왔죠. 이게 정상이 아니라는 걸 알면서도. 이번에 정리해볼 도구는 marimo라는 거고, Jupyter의 대안인데 노트북 — 여기서 말하는 노트북은 랩탑이 아니라 Jupyter처럼 셀 단위로 코드를 쪼개 실행하는 환경 — 을 .py 파일로 저장하는 게 핵심임.

본문에 자주 나올 단어 두 개만 짚고 가면, **반응형 노트북(Reactive Notebook)**은 셀 사이 의존 관계를 자동 추적해서 한 셀의 변수가 바뀌면 그걸 쓰는 다른 셀들이 자동으로 다시 실행되는 방식이고, DAG(Directed Acyclic Graph)는 marimo가 셀들 사이 관계를 비순환 의존 그래프로 강제한다는 의미. 마지막으로 PEP 723은 Python 스크립트 파일 상단에 의존성 메타데이터를 주석으로 박아넣는 표준인데, 뒤에서 한 번 더 등장함.

marimo가 실제로 다르게 하는 것#

핵심 한 줄: 노트북을 .py 파일 하나로 저장하고, 셀 간 의존성을 코드 파싱으로 추적해서 reactivity를 구현함.

여기서 따라오는 결과들이 흥미로움. .ipynb 같은 JSON 형식이 아니니까 git diff가 진짜로 읽히고, 같은 파일을 노트북으로 열 수도 있고 그냥 python notebook.py로 실행할 수도 있음. 셀 순서를 잘못 실행하거나 삭제한 셀의 변수가 메모리에 유령처럼 남는 문제가 구조적으로 사라짐. ipywidgets 안 쓰고도 슬라이더, 드롭다운, 데이터프레임 탐색기를 바로 붙일 수 있고, marimo run notebook.py 한 줄이면 같은 파일이 웹 앱으로 떠버림.

이걸 가능하게 하는 건 결국 한 가지 결정 — 노트북을 코드로 본다는 거예요. JSON 컨테이너 안에 코드와 출력과 메타데이터를 다 같이 묶어버린 .ipynb의 모델을 버리고, 그냥 Python 파일 하나로 처음부터 만든 것.

Git 친화성이 만드는 차이#

이 부분이 사실 백엔드 개발자한테는 가장 와닿을 거예요.

내 작업 패턴 기준으로 말하면, 가끔씩 데이터 검증이나 모델 추론 결과 확인 용도로 Jupyter를 띄우긴 하는데 그 결과를 동료랑 공유할 일이 생기면 늘 같은 패턴이 반복됨. .ipynb를 PR에 올리면 동료가 "어디가 바뀐 건데"라고 묻고, 결국 결과 스크린샷이랑 핵심 셀 코드만 따로 메시지로 보내는 식. 이게 진짜 비효율인데 다들 그냥 받아들이고 살았음.

marimo의 .py 저장 방식이 이걸 날려준다고 함. 평범한 Python 파일이니까 PR 리뷰가 평소처럼 되고, ruff check도 돌릴 수 있고 pytest도 붙일 수 있다는 게 사실이라면 — 직접 다 검증해본 건 아니라서 단언은 못 하지만 — 이게 가장 실용적인 차이라고 봄.

반응형이라는 양날의 검#

근데 reactivity가 항상 좋기만 한 건 아닐 수 있음. Jupyter에서 일부러 셀을 순서대로 실행 안 하는 게 의도된 워크플로우인 경우가 있거든요. 예를 들어 학습 셀 한 번 돌려두고 그 결과 객체를 다른 셀에서 이리저리 탐색하는 패턴. 이런 작업에서 자동 재실행은 오히려 방해.

찾아보니 lazy mode라는 옵션이 있어서 자동 재실행을 끌 수 있다고는 하는데, 그러면 결국 reactivity의 장점을 반쯤 포기하는 꼴 아닌가 싶음. 직접 안 굴려봐서 정확한 사용감은 모르겠는데, 적어도 "Jupyter의 자유도가 그리운 사람"한테는 마찰이 있을 것 같다는 인상.

또 한 가지, 셀 간에 같은 dataframe을 mutate하는 패턴 — df["new_col"] = ... 같은 — 은 reactivity가 변화를 못 잡아냄. 이건 함수형으로 새 dataframe을 반환하는 패턴으로 바꾸면 되는데, 사고방식 자체가 바뀌는 거라 익숙해지는 데 시간이 좀 걸릴 듯.

PEP 723 + uv 조합이 진짜 끌리는 부분#

솔직히 가장 끌렸던 게 이거임. .py 파일 상단에 의존성을 주석 메타데이터로 박아두면 uv가 그걸 읽고 격리된 환경을 자동으로 만들어서 실행하는 흐름.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "pandas==2.2.0",
#     "scikit-learn==1.4.0",
#     "marimo",
# ]
# ///

uv run marimo edit notebook.py 한 번이면 끝. requirements.txt 따로 관리할 일도 없고, 이 노트북을 받은 사람이 환경 맞추다가 헤맬 일도 없음. "이거 어떤 환경에서 만든 거야?" 질문이 사라지는 거.

엄밀히 말하면 이건 marimo만의 기능이 아님. PEP 723은 Python 표준이고 uv는 별도 도구라서, 어떤 .py든 같은 방식으로 실행할 수 있음. 다만 marimo가 이 흐름을 처음부터 자연스럽게 받아들이는 구조라는 게 의미 있는 거. 관심 있으면 PEP 723 공식 문서 한 번 훑어볼 만함.

단점과 솔직한 거리두기#

좋은 얘기만 늘어놓긴 좀 그러니까 단점도.

첫째, Jupyter 생태계가 워낙 두꺼움. Colab, JupyterHub, 회사 ML 인프라 대부분이 Jupyter 기반으로 돌아감. 개인 프로젝트에서는 marimo 자유롭게 쓸 수 있지만 팀 단위 도입은 진입 장벽이 분명히 있음. 동료한테 "이건 .py지만 노트북이야"를 매번 설명해야 한다면 그것도 코스트.

둘째, 솔직히 본인이 직접 깔아서 일주일쯤 굴려본 게 아님. 후기랑 docs 위주로 본 거라 실무 도입 시 부딪히는 자잘한 문제들 — 라이브러리 호환성, 회사 내부망 환경 동작, 메모리 사용 패턴 — 은 직접 써봐야 평가할 수 있음. 위의 평가도 어디까지나 이론적 판단인 셈.

잠깐 다른 얘기#

이거 보면서 한 가지 떠오른 게, 노트북이라는 형식 자체가 좀 묘한 위치에 있는 거 같음. 코드인데 코드보다 자유롭고, 문서인데 문서보다 실행 가능하고, 결과물인데 또 산출물은 아니고. 그래서 모델 빠르게 실험할 때는 Jupyter의 무질서가 오히려 자유도가 되고, 그 결과를 공유할 때는 그게 그대로 재앙이 되는 거. marimo가 후자를 개선하려는 시도라면 전자에서 약간 마찰이 생기는 건 어쩌면 당연한 결과 같기도 함.

정리#

marimo는 "Jupyter 만족하는데 가끔 git에 올릴 때만 답답한 사람"한테는 갈아탈 만한 도구로 보임. PEP 723 + uv 조합은 marimo와 별개로도 충분히 가져갈 만한 패턴이고요.

다만 "Jupyter는 끝났다, 다 marimo로 가자"는 톤은 좀 걸러 들어야 할 것. 도구는 워크플로우에 맞춰 고르는 거지 워크플로우를 도구에 맞추는 게 아니거든. 데이터 분석 분야에서 Jupyter의 무질서함은 의도된 자유도인 경우가 많음.

본인 계획은 다음 사이드 프로젝트의 데이터 검증 부분부터 marimo로 한 번 짜볼 생각임. 한 달쯤 굴려보고 직접 측정한 후기 — 환경 설정 시간, 동료 PR 리뷰 경험, 실제로 쓰면서 걸리적거리는 부분 — 를 따로 정리하기로.