.ipynb를 marimo로 변환하기 (marimo convert)

PART 01 Ch 04에서 marimo convert 명령을 잠깐 언급했습니다. 기존 .ipynb 파일을 marimo .py 형식으로 바꿔주는 명령입니다. 이 챕터에서 실제로 실행해보고, 변환 결과를 읽는 방법을 살펴봅니다.

변환 명령

기존 노트북 파일이 analysis.ipynb라면 다음 명령으로 변환합니다.

marimo convert analysis.ipynb -o analysis.py

-o 플래그 없이 실행하면 변환 결과가 터미널에 출력됩니다. 내용을 확인하고 싶을 때 편리합니다.

marimo convert analysis.ipynb > analysis.py

두 방법 모두 결과는 같습니다. -o를 쓰면 파일로 직접 저장되고, 리다이렉트를 쓰면 표준 출력을 파일로 저장합니다.

변환 결과 구조

analysis.ipynb에 세 개의 셀이 있었다고 가정합니다. 변환 후 생성되는 analysis.py는 이런 구조입니다.

import marimo__generated_with = "0.23.10"app = marimo.App()@app.celldef _():    import pandas as pd    df = pd.read_csv("data.csv")    return (df,)@app.celldef _(df):    summary = df.describe()    summary    return (summary,)@app.celldef _(df, summary):    print(f"행 수: {len(df)}, 컬럼 수: {len(df.columns)}")    returnif __name__ == "__main__":    app.run()

구조를 하나씩 살펴봅니다.

__generated_with = "0.23.10"

marimo가 자동으로 추가하는 버전 추적 행입니다. 어떤 버전으로 변환했는지를 파일에 기록합니다. 직접 편집할 필요는 없습니다. marimo check를 실행할 때 이 행이 없으면 warning[general-formatting] 경고가 발생합니다.

warning[general-formatting]: Expected `__generated_with` assignment for marimo version number.

@app.cell 데코레이터

Jupyter의 셀이 각각 @app.cell 함수로 변환됩니다. 함수명은 _로 시작하는 자동 생성 이름입니다. 에디터에서 작업할 때는 이 이름을 신경 쓰지 않아도 됩니다. marimo가 자동으로 관리합니다.

의존 변수가 매개변수로

def _(df): 처럼 함수가 다른 셀에서 정의한 변수를 매개변수로 받습니다. marimo가 변수 의존 관계를 분석해서 이 매개변수를 자동으로 채웁니다. DAG 구조 그대로입니다.

return (변수,)

셀이 정의하는 변수를 튜플로 반환합니다. 마지막 셀처럼 외부에 전달할 변수가 없으면 return만 씁니다. 마찬가지로 직접 수정하지 않아도 됩니다.

if __name__ == "__main__": app.run()

파일 끝에 이 두 줄이 있어야 python analysis.py로 스크립트처럼 직접 실행할 수 있습니다. marimo edit이나 marimo run으로 열 때는 이 부분이 실행되지 않습니다.

변환 후 바로 열기

변환이 끝나면 곧바로 marimo 에디터로 열어봅니다.

marimo edit analysis.py

에디터가 열리면 각 셀이 렌더링됩니다. 이 시점에서 에러가 있는 셀은 빨간색으로 표시됩니다.

marimo check로 문제 점검

에디터 없이 터미널에서 문제를 먼저 확인하고 싶다면 marimo check를 씁니다.

marimo check analysis.py

marimo check는 변수 중복 정의(MB002), 순환 의존성(MB003) 같은 구조적 오류를 비대화형으로 감지합니다. 아무 문제가 없으면 출력이 없습니다. 문제가 있으면 파일명, 행 번호, 코드 스니펫, 힌트를 함께 출력합니다.

marimo check analysis.py

아무 문제가 없으면 출력이 없습니다.

marimo check messy.py

critical[multiple-definitions]: Variable 'df' is defined in multiple cells --> messy.py:12:1Found 2 issues.

변환 직후에 marimo check를 실행하는 것이 좋습니다. 에디터를 열기 전에 구조적 오류를 파악할 수 있습니다.

변환 방향과 한계

marimo convert는 셀의 코드를 그대로 가져옵니다. 변수 의존 관계를 자동으로 재설계하지는 않습니다. 원래 노트북이 Jupyter의 수동 실행 순서에 의존하고 있었다면, 변환 후 marimo에서 그 의존 관계를 수동으로 정리해야 합니다.

다음 챕터에서 변환 후 자주 발생하는 에러 패턴과 수정 방법을 살펴봅니다.

역방향 변환

marimo 파일을 다시 .ipynb로 내보낼 수도 있습니다. 동료가 Jupyter를 쓰거나 nbconvert 기반 파이프라인이 있을 때 유용합니다.

# 실행 결과 포함marimo export ipynb analysis.py -o analysis_exported.ipynb --include-outputs# 코드만 (실행 결과 제외)marimo export ipynb analysis.py -o analysis_exported.ipynb

정리

• marimo convert notebook.ipynb -o notebook.py로 .ipynb를 marimo .py로 변환합니다.
• 변환된 파일에는 __generated_with, @app.cell 함수, if __name__ == "__main__": app.run()가 자동으로 포함됩니다.
• 변환 직후 marimo check notebook.py로 구조적 오류를 먼저 확인합니다.
• marimo edit notebook.py로 에디터를 열어 실제 셀 동작을 확인합니다.
• 역방향 변환은 marimo export ipynb로 가능합니다.