A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Deploy with Kubernetes
The marimo-operator is a Kubernetes operator that manages marimo notebook deployments. It handles persistent storage, resource allocation, and lifecycle management for notebooks running on Kubernetes clusters.
!!! tip "Quick start"
For the fastest path to running notebooks on Kubernetes, use the kubectl-marimo CLI plugin.
It handles manifest generation, port forwarding, and file synchronization automatically.
Prerequisites
- Kubernetes cluster (v1.25+)
kubectlconfigured with cluster access- Python 3.9+ with
piporuv - Cluster admin permissions (for initial operator installation)
Install the operator
Install the marimo operator on your cluster:
kubectl apply -f https://raw.githubusercontent.com/marimo-team/marimo-operator/main/deploy/install.yaml
Verify the operator is running:
kubectl get pods -n marimo-operator-system
The output should show the operator pod running:
NAME READY STATUS RESTARTS AGE
marimo-operator-controller-manager-xxxxx 1/1 Running 0 30s
Quickstart with kubectl-marimo
The kubectl-marimo plugin is the recommended way to deploy notebooks from local files.
Install the plugin
# With uv (recommended)
uv tool install kubectl-marimo
# Or with pip
pip install kubectl-marimo
Run a notebook
Edit a notebook interactively on the cluster:
kubectl marimo edit notebook.py
This command:
- Uploads your notebook to the cluster
- Creates persistent storage for your changes
- Starts the marimo server
- Sets up port forwarding to your local machine
When you stop the command (Ctrl+C), it syncs changes back to your local file and tears down the pod.
To run a notebook as a read-only application:
kubectl marimo run notebook.py
Configure resources
Configure your notebook's Kubernetes resources using frontmatter in your notebook file.
Python notebooks (.py):
# /// script
# requires-python = ">=3.12"
# dependencies = ["marimo", "pandas", "numpy"]
#
# [tool.marimo.k8s]
# image = "ghcr.io/marimo-team/marimo:latest"
# storage = "5Gi"
# [tool.marimo.k8s.resources]
# requests.cpu = "500m"
# requests.memory = "2Gi"
# limits.cpu = "2"
# limits.memory = "8Gi"
# ///
Markdown notebooks (.md):
---
title: my-analysis
image: ghcr.io/marimo-team/marimo:latest
storage: 5Gi
resources:
requests:
cpu: "500m"
memory: "2Gi"
limits:
cpu: "2"
memory: "8Gi"
---
Configuration fields
| Field | Description | Default |
|---|---|---|
title |
Resource name in Kubernetes | filename |
image |
Container image | ghcr.io/marimo-team/marimo:latest |
port |
Server port | 2718 |
storage |
Persistent volume size | none (ephemeral) |
resources |
CPU, memory, GPU requests/limits | none |
auth |
Set to "none" to disable authentication |
token auth |
env |
Environment variables | none |
Manage deployments
# Sync changes back to local file
kubectl marimo sync notebook.py
# Delete deployment
kubectl marimo delete notebook.py
# List active deployments
kubectl marimo status
GPU workloads
Specify GPU resources in your notebook frontmatter:
Python notebooks:
# /// script
# [tool.marimo.k8s.resources]
# limits."nvidia.com/gpu" = 1
# ///
Markdown notebooks:
---
resources:
limits:
nvidia.com/gpu: 1
---
The Kubernetes scheduler will place your notebook on an appropriate GPU node.
Cloud storage integration
The marimo operator supports mounting cloud storage (S3-compatible buckets, SSHFS, rsync) in your notebooks. See the operator documentation for mount configuration details.
Deploy with manifests
For advanced users who need fine-grained control, you can create MarimoNotebook resources directly.
Basic manifest
apiVersion: marimo.io/v1alpha1
kind: MarimoNotebook
metadata:
name: my-notebook
spec:
source: https://github.com/marimo-team/examples.git
storage:
size: 1Gi
Apply the manifest:
kubectl apply -f notebook.yaml
Check the status:
kubectl get marimos
Port forward to access:
kubectl port-forward svc/my-notebook 2718:2718
With GPU and sidecars
apiVersion: marimo.io/v1alpha1
kind: MarimoNotebook
metadata:
name: gpu-notebook
spec:
source: https://github.com/your-org/notebooks.git
storage:
size: 5Gi
resources:
requests:
memory: 4Gi
limits:
memory: 16Gi
nvidia.com/gpu: 1
sidecars:
- name: ssh
image: linuxserver/openssh-server:latest
exposePort: 2222
Clean up
# Via plugin (syncs changes first)
kubectl marimo delete notebook.py
# Via kubectl (does not sync)
kubectl delete marimo my-notebook
!!! warning "Sync before deleting"
Using kubectl delete directly will not sync your changes back to your local file. Use kubectl marimo delete to automatically sync before deletion.
Learn more
- marimo-operator on GitHub
- SkyPilot deployment - For multi-cloud VM deployment without Kubernetes
- Docker deployment - For container basics
- Inlining dependencies - For reproducible notebooks