marimo 생태계 한눈에 보기
marimo는 단일 명령어가 아니라 여러 기능이 조합된 생태계입니다. 이 챕터는 전체 구성을 조망하는 지도 역할을 합니다. 각 기능의 상세 사용법은 해당 PART에서 다룹니다.
CLI 명령 체계
marimo의 모든 주요 기능은 CLI로 제어합니다.
| 명령 | 역할 | 주요 사용 시점 |
|---|---|---|
marimo edit notebook.py |
브라우저 에디터에서 노트북 편집 | 개발, 분석 |
marimo run notebook.py |
앱 모드로 실행 (편집 불가) | 배포, 시연 |
marimo convert source -o out.py |
.ipynb 또는 기타 형식을 marimo .py로 변환 | Jupyter 마이그레이션 |
marimo export html notebook.py -o out.html |
출력 포함 정적 HTML로 내보내기 | 리포트 공유 |
marimo export html-wasm notebook.py -o out.wasm.html |
WASM 자체 포함 HTML (서버 불필요) | 브라우저 단독 배포 |
marimo export ipynb notebook.py -o out.ipynb |
Jupyter 형식으로 내보내기 | 기존 Jupyter 환경 공유 |
marimo export md notebook.py -o out.md |
마크다운 내보내기 | Quarto, MyST 연동 |
marimo export script notebook.py -o out.py |
위상정렬된 실행 가능 스크립트 | CI/CD 자동화 |
--sandbox 옵션을 붙이면 노트북별 격리 가상환경을 자동 생성하고 패키지 의존성을 PEP 723 인라인 메타데이터로 노트북 파일에 기록합니다.
marimo edit --sandbox analysis.pymo.ui 위젯
mo.ui 네임스페이스 아래 인터랙티브 입력 위젯이 내장되어 있습니다. 별도 라이브러리 없이 사용 가능합니다.
| 카테고리 | 주요 위젯 |
|---|---|
| 수치 입력 | mo.ui.slider, mo.ui.range_slider, mo.ui.number |
| 텍스트 입력 | mo.ui.text, mo.ui.text_area |
| 선택 | mo.ui.dropdown, mo.ui.radio, mo.ui.multiselect, mo.ui.checkbox |
| 기타 입력 | mo.ui.date, mo.ui.file, mo.ui.button, mo.ui.run_button |
| 데이터 뷰 | mo.ui.table, mo.ui.dataframe, mo.ui.data_explorer |
| 복합 | 탭, 아코디언, 사이드바, mo.hstack, mo.vstack |
위젯 값은 .value로 참조합니다. 전역 변수로 할당하면 다른 셀에서 .value를 읽을 때 반응형으로 동작합니다.
DuckDB SQL 셀
mo.sql()을 사용하면 노트북 셀에서 SQL을 직접 실행할 수 있습니다. DuckDB 엔진 기반으로 별도 데이터베이스 서버가 필요 없습니다.
result = mo.sql(f""" SELECT * FROM weather WHERE location = '{city.value}'""")f-string으로 Python 변수나 위젯 값을 SQL에 삽입할 수 있습니다. 위젯 값이 바뀌면 SQL도 자동으로 재실행됩니다. 반환 타입은 환경에 따라 Polars DataFrame 또는 Pandas DataFrame입니다.
anywidget 통합
ipywidgets 생태계에서 anywidget 프로토콜을 따르는 위젯은 mo.ui.anywidget()으로 래핑해 marimo 안에서 사용할 수 있습니다. JavaScript/CSS 기반 커스텀 시각화 라이브러리를 통합하는 주요 경로입니다.
WASM 내보내기
marimo export html-wasm 명령으로 서버 없이 브라우저에서만 실행되는 HTML을 만들 수 있습니다. Pyodide(CPython WebAssembly 포트) 기반입니다. GitHub Pages나 Cloudflare Pages에 올리면 Python 서버 없이 노트북을 공유할 수 있습니다.
단, 네이티브 C 확장이 필요한 라이브러리는 WASM에서 동작하지 않습니다. WASM 배포를 계획한다면 사용하는 패키지의 호환 여부를 먼저 확인해야 합니다. 자세한 내용은 PART 09에서 다룹니다.
AI-native 에디터
marimo 에디터는 AI 코드 완성과 셀 생성 기능을 내장하고 있습니다. 외부 LLM API 키를 설정해 사용합니다. 반응형 실행 환경이기 때문에 AI가 생성한 코드를 즉시 실행하고 결과를 확인하면서 반복할 수 있습니다.
생태계 구성 요약
marimo
├── 편집 환경
│ ├── 브라우저 내장 에디터 (marimo edit)
│ └── AI 코드 완성 내장
├── 실행 환경
│ ├── 반응형 노트북 (DAG 기반)
│ ├── 앱 모드 (marimo run)
│ └── 스크립트 실행 (python notebook.py)
├── UI
│ ├── mo.ui 내장 위젯
│ ├── mo.md, mo.hstack, mo.vstack, 탭, 아코디언
│ └── anywidget 통합
├── 데이터
│ ├── DuckDB SQL 셀 (mo.sql)
│ ├── Polars / Pandas 연동
│ └── mo.cache / mo.persistent_cache
├── 내보내기
│ ├── 정적 HTML, WASM HTML
│ ├── .ipynb (Jupyter 역방향 내보내기)
│ └── 마크다운, 스크립트
└── 패키지 관리
├── uv 통합
└── --sandbox (노트북별 격리 환경, PEP 723)
이 구조를 머릿속에 두고 이후 PART를 읽으면 각 기능이 전체 그림에서 어디에 위치하는지 파악하기 쉽습니다.