techstay Marimo Skill
Marimo is an open-source reactive Python notebook that reimagines traditional Jupyter notebooks as reproducible, interactive, and shareable Python programs.
Quick Reference
| What you want to do | How to do it |
|---|---|
| Create a new notebook | Run marimo edit or marimo edit notebook.py |
| Add UI input components | Load references/ui-inputs.md, use mo.ui.* components |
| Write SQL queries | Load references/sql-data.md, create a SQL cell |
| Deploy as a web app | Load references/apps-deployment.md, run marimo run notebook.py |
| Understand reactive execution | Load references/core-concepts.md, learn the DAG execution model |
| View CLI commands | Load references/cli-commands.md |
Key Workflow Rules
⚠️ Most Common Pitfalls
Mutations Are Not Tracked
Avoid:
- ❌ Defining a variable in one cell and mutating it in another
- ❌ Using
list.append(),df['col'] = values, and similar mutation operations
Follow:
- ✅ Complete all mutations in the same cell where the variable is defined
- ✅ Create new variables instead of mutating old ones (
new_list = old_list + [item]) - ✅ Use a pure functional style for data processing
Global Variable Names Must Be Unique
Avoid:
- ❌ Defining a global variable with the same name in multiple cells
- ❌ Imported module names conflicting with variable names
Follow:
- ✅ Define each global variable in exactly one cell
- ✅ Use underscore prefix for local variables (
_temp_var) - ✅ Wrap temporary variables inside functions
Reference Files — Load On Demand
Do not load all at once. Only load the files needed for the current task.
| File | Content | When to load |
|---|---|---|
references/core-concepts.md |
Reactive execution model, DAG, variable rules | When you need to understand how Marimo works |
references/ui-inputs.md |
Detailed usage of all UI input components | When you need to add interactive controls |
references/sql-data.md |
SQL cells, database connections, data processing | When you need to use SQL queries |
references/apps-deployment.md |
App deployment, layout options, grid/slides | When you need to deploy as a web app |
references/cli-commands.md |
All CLI commands and options | When you need to check command-line usage |
Common Mistakes
| ❌ Wrong | ✅ Right | Reason |
|---|---|---|
df['new_col'] = values in another cell |
Complete in the same cell | Mutations are not tracked |
my_list.append(x) in another cell |
Create new list: my_list + [x] |
Mutations are not tracked |
Define x = ... in multiple cells |
Define each variable in only one cell | Violates uniqueness rule |
| Use global variables to pass intermediate results | Wrap in functions or use return values | Avoids hidden dependencies |
Quick Examples
Basic Notebook Structure
# Cell 1: Imports
import marimo as mo
import pandas as pd
# Cell 2: Data preparation
data = {"x": [1, 2, 3], "y": [4, 5, 6]}
df = pd.DataFrame(data)
# Cell 3: Add interactivity
slider = mo.ui.slider(1, 10, value=5)
slider
# Cell 4: Reactive computation
filtered_df = df[df["x"] < slider.value]
filtered_df
Running Notebooks
# Edit mode
marimo edit notebook.py
# Run as app
marimo run notebook.py
# Convert to script execution
python notebook.py