docs/guides/deploying/deploying_kubernetes.md
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.
kubectl configured with cluster accesspip or uvInstall 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
The kubectl-marimo plugin is the recommended way to deploy notebooks from local files.
# With uv (recommended)
uv tool install kubectl-marimo
# Or with pip
pip install kubectl-marimo
Edit a notebook interactively on the cluster:
kubectl marimo edit notebook.py
This command:
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 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"
---
| 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 |
# Sync changes back to local file
kubectl marimo sync notebook.py
# Delete deployment
kubectl marimo delete notebook.py
# List active deployments
kubectl marimo status
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.
The marimo operator supports mounting cloud storage (S3-compatible buckets, SSHFS, rsync) in your notebooks. See the operator documentation for mount configuration details.
For advanced users who need fine-grained control, you can create MarimoNotebook resources directly.
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
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
# 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.