Skip to content

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.

docs: deployment on slurm (#7376)

Dylan Madisetti50e3e137ed71
diff --git a/docs/guides/deploying/deploying_slurm.md b/docs/guides/deploying/deploying_slurm.md
new file mode 100644
index 0000000000..8d59c55deb
--- /dev/null
+++ b/docs/guides/deploying/deploying_slurm.md
@@ -0,0 +1,153 @@
+# Deploy on Slurm/HPC Clusters
+
+This guide shows how to run marimo notebooks on Slurm-managed clusters, including traditional HPC systems and Slurm-on-Kubernetes setups like [SUNK](https://docs.coreweave.com/docs/products/sunk) (CoreWeave).
+
+Since marimo notebooks are pure Python scripts, it's easy to submit as Slurm jobs for both interactive development and batch processing.
+
+## Interactive Development
+
+For interactive development, submit a job that runs `marimo edit` and connect via SSH port forwarding.
+
+### Submit the job
+
+Create a script (`run_marimo.sh`):
+
+```bash
+#!/bin/bash
+#SBATCH --job-name=marimo
+#SBATCH --output=marimo-%j.out
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=16GB
+#SBATCH --time=4:00:00
+
+# module load or otherwise set up environment
+
+python -m marimo edit notebook.py --headless --port 3000
+```
+
+Submit it:
+
+```bash
+sbatch run_marimo.sh
+```
+
+### Connect with port forwarding
+
+Once the job is running, find the compute node and create an SSH tunnel:
+
+```bash
+# Find which node your job is running on
+squeue -u $USER -o "%.18i %.9P %.8j %.8u %.2t %.10M %.6D %R"
+
+# Create tunnel (replace NODE with actual node name)
+ssh -L 3000:NODE:3000 [email protected]
+```
+
+Open `http://localhost:3000` in your browser.
+
+## Running as Batch Jobs
+
+marimo notebooks can run as batch jobs using `app.run()`. Use `mo.cli_args()` to pass parameters:
+
+```python
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
+
+import marimo
+
+app = marimo.App()
+
+
+def _():
+ import marimo as mo
+ args = mo.cli_args()
+ print(f"Running with: {args}")
+ return
+
+
+if __name__ == "__main__":
+ app.run()
+```
+
+Submit as a job:
+
+```bash
+#!/bin/bash
+#SBATCH --job-name=marimo-job
+#SBATCH --output=marimo-%j.out
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=16GB
+
+python notebook.py --learning-rate 0.01 --epochs 100
+```
+
+## GPU Jobs
+
+Add GPU resources to your SBATCH directives:
+
+```bash
+#!/bin/bash
+#SBATCH --job-name=marimo-gpu
+#SBATCH --partition=gpu
+#SBATCH --gres=gpu:1
+#SBATCH --cpus-per-task=8
+#SBATCH --mem=32GB
+
+python notebook.py
+```
+
+## Self-contained notebooks
+
+You can embed SBATCH directives directly in your notebook file, making it fully self-contained:
+
+```python
+#!/usr/bin/env -S python -m marimo edit --sandbox
+#SBATCH --job-name=marimo-job
+#SBATCH --output=marimo-%j.out
+#SBATCH --cpus-per-task=4
+#SBATCH --mem=16GB
+
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
+
+import marimo
+
+app = marimo.App()
+
+
+def _():
+ import marimo as mo
+ print("Hello World!")
+ return
+
+
+if __name__ == "__main__":
+ app.run()
+```
+
+Make executable and submit directly:
+
+```bash
+chmod +x notebook.py
+sbatch notebook.py
+```
+
+For this sandboxing to work correctly, [uv](https://docs.astral.sh/uv/getting-started/installation/) should be installed.
+Alternatively, following hashbang `#!/usr/bin/env -S uv run marimo edit --sandbox`.
+
+## Learn more
+
+- [Slurm examples](https://github.com/marimo-team/marimo/tree/main/examples/slurm) - Complete working examples
+- [Slurm documentation](https://slurm.schedmd.com/documentation.html)
+- [SUNK (Slurm on Kubernetes)](https://docs.coreweave.com/docs/products/sunk)
+- [marimo CLI arguments](../../api/cli_args.md)
diff --git a/docs/guides/deploying/index.md b/docs/guides/deploying/index.md
index 15f4234e28..344ca02722 100644
--- a/docs/guides/deploying/index.md
+++ b/docs/guides/deploying/index.md
@@ -26,7 +26,8 @@ Here are a few ways to deploy an edit server on a remote instance:
1. With [ssh-port forwarding](../../faq.md#faq-remote), using `marimo edit --headless`.
2. Via docker and our [prebuilt containers](prebuilt_containers.md).
3. Via a deployment service [such as Railway](deploying_railway.md).
-4. [Behind JupyterHub](../../faq.md#faq-jupyter-hub).
+4. [On Slurm/HPC clusters](deploying_slurm.md).
+5. [Behind JupyterHub](../../faq.md#faq-jupyter-hub).
## Deploying as read-only apps
@@ -36,6 +37,7 @@ These guides help you deploy marimo notebooks as read-only apps.
| :------------------------------ | :------------------------------------------------------- |
| [programmatically](./programmatically.md) | Programmatically run and customize read-only marimo apps |
| [deploying_docker](./deploying_docker.md) | Deploy with Docker |
+| [deploying_slurm](./deploying_slurm.md) | Run on HPCs/SUNK with slurm |
| [authentication](./authentication.md) | Authentication and security |
| [deploying_public_gallery](./deploying_public_gallery.md) | Deploy to our public gallery |
| [deploying_hugging_face](./deploying_hugging_face.md) | Deploy to Hugging Face |