uv-scripts/marimo

1---2viewer: false3tags:4  - uv-script5  - marimo6  - tutorial7---8 9# Marimo UV Scripts10 11[Marimo](https://marimo.io/) notebooks that work as both **interactive tutorials** and **batch scripts**.12 13## What is this?14 15Marimo notebooks are pure Python files that can be:16- **Edited interactively** with a reactive notebook interface17- **Run as scripts** with `uv run` - same as any UV script18 19This makes them perfect for tutorials and educational content where you want users to explore step-by-step, but also run the whole thing as a batch job.20 21## Available Scripts22 23| Script | Description |24|--------|-------------|25| `getting-started.py` | Introduction to UV scripts and HF datasets |26| `train-image-classifier.py` | Fine-tune a Vision Transformer on image classification |27| `_template.py` | Minimal template for creating your own notebooks |28 29## Usage30 31### Run as a script32 33```bash34# Get dataset info35uv run https://huggingface.co/datasets/uv-scripts/marimo/raw/main/getting-started.py --dataset squad36 37# Train an image classifier38uv run https://huggingface.co/datasets/uv-scripts/marimo/raw/main/train-image-classifier.py \39    --dataset beans \40    --epochs 3 \41    --output-repo your-username/beans-vit42```43 44### Run interactively45 46```bash47# Clone and edit locally48git clone https://huggingface.co/datasets/uv-scripts/marimo49cd marimo50 51# Open in marimo editor (--sandbox auto-installs dependencies)52uvx marimo edit --sandbox getting-started.py53uvx marimo edit --sandbox train-image-classifier.py54```55 56### Run on HF Jobs (GPU)57 58```bash59# Train image classifier with GPU60hf jobs uv run --flavor l4x1 --secrets HF_TOKEN \61    https://huggingface.co/datasets/uv-scripts/marimo/raw/main/train-image-classifier.py \62    -- --dataset beans --output-repo your-username/beans-vit --epochs 5 --push-to-hub63```64 65## Why Marimo?66 67- **Reactive**: Cells automatically re-run when dependencies change68- **Pure Python**: No JSON, git-friendly, readable as plain code69- **Self-contained**: Inline dependencies via PEP 723 metadata70- **Dual-mode**: Same file works as notebook and script71 72## Create Your Own Marimo UV Script73 74Use `_template.py` as a starting point:75 76```bash77# Clone and copy the template78git clone https://huggingface.co/datasets/uv-scripts/marimo79cp marimo/_template.py my-notebook.py80 81# Edit interactively82uvx marimo edit --sandbox my-notebook.py83 84# Test as script85uv run my-notebook.py --help86```87 88## Recipes89 90### Add explanation (notebook only)91 92```python93mo.md("""94## This is a heading95 96This text explains what's happening. Only shows in interactive mode.97""")98```99 100### Show output in both modes101 102```python103# print() shows in terminal (script) AND cell output (notebook)104print(f"Loaded {len(data)} items")105```106 107### Interactive control with CLI fallback108 109```python110# Parse CLI args first111parser = argparse.ArgumentParser()112parser.add_argument("--count", type=int, default=10)113args, _ = parser.parse_known_args()114 115# Create UI control with CLI default116slider = mo.ui.slider(1, 100, value=args.count, label="Count")117 118# Use it - works in both modes119count = slider.value  # UI value in notebook, CLI value in script120```121 122### Show visuals (notebook only)123 124```python125# mo.md() with images, mo.ui.table(), etc. only display in notebook126mo.ui.table(dataframe)127 128# For script mode, also print summary129print(f"DataFrame has {len(df)} rows")130```131 132### Conditional notebook-only code133 134```python135# Check if running interactively136if hasattr(mo, 'running_in_notebook') and mo.running_in_notebook():137    # Heavy visualization only in notebook138    show_complex_plot(data)139```140 141## Best Practices142 1431. **Always include `print()` for important output** - It works in both modes1442. **Use argparse for all configuration** - CLI args work everywhere1453. **Add `mo.md()` explanations between steps** - Makes tutorials readable1464. **Test in script mode first** - Ensure it works without interactivity1475. **Keep dependencies minimal** - Add `marimo` plus only what you need148 149## Learn More150 151- [Marimo documentation](https://docs.marimo.io/)152- [UV scripts guide](https://docs.astral.sh/uv/guides/scripts/)153- [uv-scripts organization](https://huggingface.co/uv-scripts)154