Spaces에서 marimo 사용하기

Spaces에서 marimo 사용하기

marimo는 노트북을 데이터플로우 그래프로 모델링하는 Python용 반응형 노트북이에요. 셀을 실행하거나 UI 요소와 상호작용하면 marimo가 영향받는 셀을 자동으로 실행(또는 stale로 표시)해 코드와 출력의 일관성을 유지하고 버그를 미리 방지해요. 모든 marimo 노트북은 순수 Python으로 저장되며, 스크립트로 실행 가능하고 앱으로 배포 가능해요.

출처: 문서

본문

핵심 기능:

  • ⚡️ reactive: 셀을 실행하면 marimo가 반응적으로 모든 의존 셀을 실행하거나 stale로 표시해요.
  • 🖐️ interactive: 슬라이더, 테이블, 플롯 등을 Python에 바인딩 — 콜백 없이요.
  • 🔬 reproducible: 숨은 상태 없음, 결정적 실행, 내장 패키지 관리.
  • 🏃 executable: CLI 인수로 매개변수화된 Python 스크립트로 실행.
  • 🛜 shareable: 대화형 웹 앱이나 슬라이드로 배포, WASM으로 브라우저에서 실행.
  • 🛢️ designed for data: SQL로 데이터프레임과 데이터베이스 조회, 데이터프레임 필터·검색.

Spaces에 marimo 앱 배포하기

Space에서 marimo를 시작하려면 아래 버튼을 클릭하세요.

이렇게 하면 marimo의 Docker 템플릿으로 Space 빌드가 시작돼요. 성공하면 marimo 소개 노트북과 비슷한 앱이 보여요.

marimo 앱 커스터마이즈하기

marimo Space를 만들면 시작을 돕는 몇 가지 핵심 파일이 생겨요:

1. app.py

앱 로직을 정의하는 주요 marimo 노트북 파일이에요. marimo 노트북은 @app.cell 데코레이터로 셀을 정의하는 순수 Python 파일이에요. 노트북·앱 구축에 대해 더 배우려면 marimo 문서를 참고하세요. 앱이 커지면 코드를 모듈로 정리해 메인 노트북으로 가져올 수 있어요.

2. Dockerfile

marimo 앱의 Dockerfile은 marimo에 시스템 의존성이 거의 없어 최소적이에요. 핵심 요구사항:

  • requirements.txt에 나열된 의존성을 설치해요(uv 사용).
  • 보안을 위해 non-root 사용자를 만들어요.
  • marimo run app.py로 앱을 실행해요.

애플리케이션이 추가 시스템 의존성, 권한, 다른 CLI 플래그를 요구하면 이 파일을 수정해야 할 수 있어요.

3. requirements.txt

Space가 requirements.txt에 나열된 의존성을 자동으로 설치해요. 최소한 marimo를 이 파일에 포함해야 해요. 앱에 필요한 다른 패키지도 추가해야 해요.

marimo Space 템플릿은 요구사항에 따라 확장할 수 있는 기본 설정을 제공해요. 배포되면 노트북이 "app mode"로 실행돼 코드 셀을 숨기고 대화형 출력만 보여줘요 — 최종 사용자와 공유하기에 완벽해요. Dockerfile의 marimo run 명령에 --include-code를 추가하면 코드 셀을 앱에 포함하도록 선택할 수 있어요.

문제 해결

문제가 생기면:

  1. marimo run app.py로 노트북이 로컬에서 app mode로 실행되는지 확인한다.
  2. 모든 필수 패키지가 requirements.txt에 있는지 확인한다.
  3. 포트 구성이 일치하는지 확인한다(Spaces 기본값은 7860).
  4. Python 오류가 없는지 Space 로그를 확인한다.

더 알아보기 (Learn more)