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: polish tutorial notebooks (#9573)

Péter Gyarmatif924146dbac3
diff --git a/frontend/src/components/home/components.tsx b/frontend/src/components/home/components.tsx
index 163d0eabef..03ebcc4ff5 100644
--- a/frontend/src/components/home/components.tsx
+++ b/frontend/src/components/home/components.tsx
@@ -16,6 +16,7 @@ import {
LinkIcon,
MessagesSquareIcon,
OrbitIcon,
+ PackageIcon,
YoutubeIcon,
} from "lucide-react";
import type React from "react";
@@ -58,6 +59,11 @@ const TUTORIALS: Record<
FileIcon,
"Understand marimo's pure-Python file format",
],
+ "external-dependencies": [
+ "External dependencies",
+ PackageIcon,
+ "Declare dependencies with Python script metadata",
+ ],
"for-jupyter-users": [
"For Jupyter users",
OrbitIcon,
diff --git a/marimo/_tutorials/__init__.py b/marimo/_tutorials/__init__.py
index c1ceea7550..f11e729602 100644
--- a/marimo/_tutorials/__init__.py
+++ b/marimo/_tutorials/__init__.py
@@ -18,6 +18,7 @@ PythonTutorial = Literal[
"sql",
"layout",
"fileformat",
+ "external-dependencies",
"for-jupyter-users",
]
@@ -32,6 +33,7 @@ tutorial_order: list[Tutorial] = [
"sql",
"layout",
"fileformat",
+ "external-dependencies",
"markdown-format",
"for-jupyter-users",
]
diff --git a/marimo/_tutorials/dataflow.py b/marimo/_tutorials/dataflow.py
index 419ea99ae5..3378b0b8b6 100644
--- a/marimo/_tutorials/dataflow.py
+++ b/marimo/_tutorials/dataflow.py
@@ -10,7 +10,7 @@
import marimo
-__generated_with = "0.19.7"
+__generated_with = "0.23.6"
app = marimo.App()
@@ -96,14 +96,12 @@ def _(mo):
@app.cell
def _(amplitude, mo, period, plot_wave):
- mo.md(
- f"""
- {mo.as_html(plot_wave(amplitude, period))}
+ mo.md(f"""
+ {mo.as_html(plot_wave(amplitude, period))}
- - `refs: {mo.refs()}`
- - `defs: {mo.defs()}`
- """
- )
+ - `refs: {mo.refs()}`
+ - `defs: {mo.defs()}`
+ """)
return
diff --git a/marimo/_tutorials/external_dependencies.py b/marimo/_tutorials/external_dependencies.py
new file mode 100644
index 0000000000..8ac02d8f7d
--- /dev/null
+++ b/marimo/_tutorials/external_dependencies.py
@@ -0,0 +1,131 @@
+# Copyright 2026 Marimo. All rights reserved.
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# "wigglystuff==0.5.0",
+# ]
+# ///
+
+import marimo
+
+__generated_with = "0.23.6"
+app = marimo.App()
+
+
[email protected](hide_code=True)
+def _(mo):
+ mo.md("""
+ # External dependencies
+
+ marimo notebooks are Python scripts. That means you can use Python
+ standards for scripts, including
+ [PEP 723](https://peps.python.org/pep-0723/) inline metadata, to declare
+ the Python version and packages that a notebook needs.
+ """)
+ return
+
+
[email protected](hide_code=True)
+def _(check_dependencies):
+ check_dependencies()
+ return
+
+
[email protected](hide_code=True)
+def _(mo):
+ mo.md(r"""
+ This notebook starts with a metadata block like this:
+
+ ```python
+ # /// script
+ # requires-python = ">=3.12"
+ # dependencies = [
+ # "marimo",
+ # "wigglystuff==0.5.0",
+ # ]
+ # ///
+ ```
+
+ Tools that understand PEP 723 can read this block and create an
+ environment with the right dependencies. The rest of the file remains a
+ regular Python script.
+ """)
+ return
+
+
[email protected](hide_code=True)
+def _(mo):
+ mo.md("""
+ Once a dependency is declared, import it normally in a cell.
+
+ Here we'll use `wigglystuff.Slider2D`, an anywidget, and wrap it with
+ `mo.ui.anywidget` so marimo can make it reactive.
+ """)
+ return
+
+
+def _(Slider2D, missing_packages, mo):
+ if missing_packages:
+ widget = None
+ else:
+ widget = mo.ui.anywidget(
+ Slider2D(
+ width=320,
+ height=320,
+ x_bounds=(-2.0, 2.0),
+ y_bounds=(-1.0, 1.5),
+ )
+ )
+ widget
+ return (widget,)
+
+
+def _(mo, widget):
+ if widget is not None:
+ mo.callout(
+ f"x = {widget.x:.3f}, y = {widget.y:.3f}; "
+ f"bounds {widget.x_bounds} / {widget.y_bounds}"
+ )
+ return
+
+
[email protected](hide_code=True)
+def _(missing_packages, mo):
+ module_not_found_explainer = mo.md(
+ """
+ ## Oops!
+
+ It looks like this environment is missing **wigglystuff**.
+
+ Use the package manager panel on the left to install **wigglystuff**,
+ then restart the tutorial. You can also start the notebook with a tool
+ that reads PEP 723 script metadata.
+ """
+ ).callout(kind="warn")
+
+ def check_dependencies():
+ if missing_packages:
+ return module_not_found_explainer
+
+ return (check_dependencies,)
+
+
+def _():
+ import marimo as mo
+
+ try:
+ from wigglystuff import Slider2D
+
+ missing_packages = False
+ except ModuleNotFoundError:
+ Slider2D = None
+ missing_packages = True
+ return Slider2D, missing_packages, mo
+
+
+if __name__ == "__main__":
+ app.run()
diff --git a/marimo/_tutorials/fileformat.py b/marimo/_tutorials/fileformat.py
index ad8c416edd..908f69a949 100644
--- a/marimo/_tutorials/fileformat.py
+++ b/marimo/_tutorials/fileformat.py
@@ -1,4 +1,10 @@
# Copyright 2026 Marimo. All rights reserved
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
import marimo
@@ -29,7 +35,7 @@ def _(mo):
- 🤖 legible for both humans and machines
- ✏️ formattable using your tool of choice
- ➕ easily versioned with git, producing small diffs
- - 🐍 usable as Python scripts, with UI elements taking their default values
+ - 🐍 usable as Python scripts, with UI elements taking their default values
- 🧩 modular, exposing functions and classes that can be imported from the notebook
""")
return
@@ -134,12 +140,12 @@ def _(mo):
{
"Cells are functions": """
In the `dataflow` tutorial, we saw that cells are like functions mapping
- their refs (the global variables they uses but don't define) to their
+ their refs (the global variables they use but don't define) to their
defs (the global variables they define). The generated code makes this
analogy explicit.
In the generated code, there is a function for each cell. The arguments
- of the function are the cell's refs , and its returned variables are
+ of the function are the cell's refs, and its returned variables are
its defs that are referenced by other cells.
For example, the code
diff --git a/marimo/_tutorials/for_jupyter_users.py b/marimo/_tutorials/for_jupyter_users.py
index 381e6510f9..03cdaf91a7 100644
--- a/marimo/_tutorials/for_jupyter_users.py
+++ b/marimo/_tutorials/for_jupyter_users.py
@@ -1,8 +1,14 @@
# Copyright 2026 Marimo. All rights reserved.
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
import marimo
-__generated_with = "0.19.7"
+__generated_with = "0.23.6"
app = marimo.App(app_title="marimo for Jupyter users")
@@ -47,7 +53,7 @@ def _(mo):
marimo 'reacts' to the change in `x` and automatically recalculates `y`!
**Explanation.** marimo reads the code in your cells and understands the
- dependences between them, based on the variables that each cell declares and
+ dependencies between them, based on the variables that each cell declares and
references. When you execute one cell, marimo automatically executes all other
cells that depend on it, not unlike a spreadsheet.
@@ -232,11 +238,9 @@ def _(mo):
@app.cell
def _(mo, slider):
- mo.md(
- f"""
- The value of {slider} is {slider.value}.
- """
- )
+ mo.md(f"""
+ The value of {slider} is {slider.value}.
+ """)
return
diff --git a/marimo/_tutorials/intro.py b/marimo/_tutorials/intro.py
index f4fb65d6e9..7e2a0f4cc0 100644
--- a/marimo/_tutorials/intro.py
+++ b/marimo/_tutorials/intro.py
@@ -1,4 +1,10 @@
# Copyright 2026 Marimo. All rights reserved.
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
import marimo
@@ -74,7 +80,7 @@ def _(mo):
cells.
marimo reads your cells and models the dependencies among them: whenever
- a cell that defines a global variable is run, marimo
+ a cell that defines a global variable is run, marimo
**automatically runs** all cells that reference that variable.
Reactivity keeps your program state and outputs in sync with your code,
@@ -97,14 +103,14 @@ def _(changed, mo):
Reactivity ensures that your notebook state is always
consistent, which is crucial for doing good science; it's also what
- enables marimo notebooks to double as tools and apps.
+ enables marimo notebooks to double as tools and apps.
"""
)
if changed
else mo.md(
"""
**🌊 See it in action.** In the next cell, change the value of the
- variable `changed` to `True`, then click the run button.
+ variable `changed` to `True`, then click the run button.
"""
)
)
@@ -125,7 +131,7 @@ def _(mo):
"""
The order of cells on the page has no bearing on
the order in which cells are executed: marimo knows that a cell
- reading a variable must run after the cell that defines it. This
+ reading a variable must run after the cell that defines it. This
frees you to organize your code in the way that makes the most
sense for you.
"""
@@ -237,7 +243,7 @@ def _(mo):
- easily versioned with git, yielding minimal diffs
- legible for both humans and machines
- formattable using your tool of choice,
- - usable as Python scripts, with UI elements taking their default
+ - usable as Python scripts, with UI elements taking their default
values, and
- importable by other modules (more on that in the future).
""")
@@ -300,6 +306,7 @@ def _(mo):
- `sql`: how to use SQL
- `layout`: layout elements in marimo
- `fileformat`: how marimo's file format works
+ - `external-dependencies`: how to declare notebook dependencies
- `markdown-format`: for using `.md` files in marimo
- `for-jupyter-users`: if you are coming from Jupyter
@@ -309,7 +316,7 @@ def _(mo):
marimo tutorial dataflow
```
- In addition to tutorials, we have examples in our
+ In addition to tutorials, we have examples in
[our GitHub repo](https://www.github.com/marimo-team/marimo/tree/main/examples).
""")
return
diff --git a/marimo/_tutorials/layout.py b/marimo/_tutorials/layout.py
index c815d06706..c5e7f672bb 100644
--- a/marimo/_tutorials/layout.py
+++ b/marimo/_tutorials/layout.py
@@ -1,4 +1,10 @@
# Copyright 2026 Marimo. All rights reserved.
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
import marimo
diff --git a/marimo/_tutorials/markdown.py b/marimo/_tutorials/markdown.py
index 2074a5c3a0..df29a2c4c0 100644
--- a/marimo/_tutorials/markdown.py
+++ b/marimo/_tutorials/markdown.py
@@ -11,7 +11,7 @@
import marimo
-__generated_with = "0.19.7"
+__generated_with = "0.23.6"
app = marimo.App()
@@ -77,18 +77,18 @@ def _(mo):
```python3
mo.md(
r'''
- \[
+ $$
f: \mathbf{R} \to \mathbf{R}
- \]
+ $$
'''
)
```
renders the display math
- \[
+ $$
f: \mathbf{R} \to \mathbf{R}.
- \]
+ $$
""")
return
@@ -129,7 +129,7 @@ def _(mo):
## Interpolating Python values
You can interpolate Python values into markdown using
- `f-strings` and marimo's ` as_html` function. This lets you create
+ `f-strings` and marimo's `as_html` function. This lets you create
markdown whose contents depend on data that changes at runtime.
Here are some examples.
@@ -188,7 +188,9 @@ def _(mo):
@app.cell
def _(leaves, mo):
- mo.md(f"""Your leaves: {"🍃" * leaves.value}""")
+ mo.md(f"""
+ Your leaves: {"🍃" * leaves.value}
+ """)
return
@@ -290,31 +292,27 @@ def _(mo, np, plt):
@app.cell
def _(amplitude, mo, period):
- mo.md(
- f"""
+ mo.md(f"""
**A sin curve.**
- {amplitude}
- {period}
- """
- )
+ """)
return
@app.cell
def _(amplitude, mo, period, plotsin):
- mo.md(
- rf"""
+ mo.md(rf"""
You're viewing the graph of
- \[
+ $$
f(x) = {amplitude.value}\sin((2\pi/{period.value:0.2f})x),
- \]
+ $$
with $x$ ranging from $0$ to $2\pi$.
{mo.as_html(plotsin(amplitude.value, period.value))}
- """
- )
+ """)
return
diff --git a/marimo/_tutorials/markdown_format.md b/marimo/_tutorials/markdown_format.md
index 28f1818965..d633feae2e 100644
--- a/marimo/_tutorials/markdown_format.md
+++ b/marimo/_tutorials/markdown_format.md
@@ -1,6 +1,6 @@
---
title: Markdown
-marimo-version: 0.13.2
+marimo-version: 0.23.6
author: Marimo Team
description: >-
Markdown is a lightweight markup language with plain text formatting syntax. `marimo`
@@ -13,9 +13,10 @@ pyproject: |-
"duckdb==1.2.2",
"matplotlib==3.10.1",
"sqlglot==26.16.2",
+ "pandas==2.3.3",
+ "pyarrow==23.0.0",
]
---
-
# Markdown file format
By default, marimo notebooks are stored as pure Python files. However,
@@ -96,7 +97,7 @@ form
```python {.marimo hide_code="true"}
form = (
mo.md('''
- **Just how great is markdown?.**
+ **Just how great is markdown?**
{markdown_is_awesome}
@@ -152,7 +153,9 @@ supposed to be computed, and what values are static. To interpolate Python
values, just use a Python cell:
```python {.marimo}
-mo.md(f"""Like so: {"🍃" * 7}""")
+mo.md(f"""
+Like so: {"🍃" * 7}
+""")
```
`````python {.marimo hide_code="true"}
@@ -182,12 +185,12 @@ This is a markdown cell with an execution block in it
````
It's not likely that you'll run into this issue, but rest assured that marimo
-is working behind the scenes to keep your notebooks unambiguous and clean as
+is working behind the scenes to keep your notebooks unambiguous and as clean as
possible.
<!---->
### Saving multicolumn mode
-Multicolumn mode works, but the first cell in a column must be a python cell in
+Multicolumn mode works, but the first cell in a column must be a Python cell in
order to specify column start and to save correctly:
````md
@@ -199,7 +202,7 @@ print("First cell in column 1")
### Naming cells
Since the markdown notebook really is just markdown, you can't import from a
-markdown notebook cells like you can in a python notebook; but you can still
+markdown notebook cells like you can in a Python notebook; but you can still
give your cells a name:
````md
@@ -262,8 +265,8 @@ FROM range(1, {sample_count.value + 1}) i;
## Converting back to the Python file format
-The markdown format is supposed to lower the barrier for writing text heavy
-documents, it's not meant to be a full replacement for the Python notebook
+The markdown format is supposed to lower the barrier for writing text-heavy
+documents; it's not meant to be a full replacement for the Python notebook
format. You can always convert back to a Python notebook if you need to:
```bash
@@ -272,8 +275,8 @@ $ marimo convert my_marimo.md > my_marimo.py
<!---->
## More on markdown
-Be sure to checkout the markdown.py tutorial (`marimo tutorial markdown`) for
-more information on to type-set and render markdown in marimo.
+Be sure to check out the markdown.py tutorial (`marimo tutorial markdown`) for
+more information on how to typeset and render markdown in marimo.
```python {.marimo hide_code="true"}
import marimo as mo
diff --git a/marimo/_tutorials/plots.py b/marimo/_tutorials/plots.py
index d655711d2c..fd4a78fb2e 100644
--- a/marimo/_tutorials/plots.py
+++ b/marimo/_tutorials/plots.py
@@ -10,7 +10,7 @@
import marimo
-__generated_with = "0.19.11"
+__generated_with = "0.23.6"
app = marimo.App()
diff --git a/marimo/_tutorials/sql.py b/marimo/_tutorials/sql.py
index 85ae236ab8..717ea3a243 100644
--- a/marimo/_tutorials/sql.py
+++ b/marimo/_tutorials/sql.py
@@ -2,9 +2,12 @@
# /// script
# requires-python = ">=3.12"
# dependencies = [
+# "altair==6.1.0",
# "duckdb==1.2.2",
# "marimo",
+# "matplotlib==3.10.9",
# "pandas==2.2.3",
+# "plotly==6.7.0",
# "polars==1.27.1",
# "pyarrow==19.0.1",
# "sqlglot==26.13.0",
diff --git a/marimo/_tutorials/ui.py b/marimo/_tutorials/ui.py
index f9eb0e4f3f..78d383a33c 100644
--- a/marimo/_tutorials/ui.py
+++ b/marimo/_tutorials/ui.py
@@ -1,8 +1,14 @@
# Copyright 2026 Marimo. All rights reserved.
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "marimo",
+# ]
+# ///
import marimo
-__generated_with = "0.19.7"
+__generated_with = "0.23.6"
app = marimo.App()
@@ -43,7 +49,9 @@ def _(mo):
@app.cell
def _(mo, slider):
- mo.md(f"and here's its value: **{slider.value}**.")
+ mo.md(f"""
+ and here's its value: **{slider.value}**.
+ """)
return
@@ -103,7 +111,7 @@ def _(mo):
@app.cell(hide_code=True)
def _(mo):
mo.md("""
- marimo has a [large library of simple UI elements](https://docs.marimo.io/api/inputs/index.html). Here are a just few examples:
+ marimo has a [large library of simple UI elements](https://docs.marimo.io/api/inputs/index.html). Here are just a few examples:
""")
return
@@ -212,7 +220,9 @@ def _(file_upload):
@app.cell
def _(basic_ui_elements, mo):
- mo.md(f"To see more examples, use this dropdown: {basic_ui_elements}")
+ mo.md(f"""
+ To see more examples, use this dropdown: {basic_ui_elements}
+ """)
return
@@ -332,9 +342,9 @@ def _(dictionary):
@app.cell(hide_code=True)
def _(composite_elements, mo):
- mo.md(
- f"To see additional composite elements, use this dropdown: {composite_elements}"
- )
+ mo.md(f"""
+ To see additional composite elements, use this dropdown: {composite_elements}
+ """)
return
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 556cc6366d..27dc721cb7 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -3701,6 +3701,7 @@ components:
anyOf:
- enum:
- dataflow
+ - external-dependencies
- fileformat
- for-jupyter-users
- intro
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 8085de21a0..e4b05c760a 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -5568,6 +5568,7 @@ export interface components {
tutorialId:
| (
| "dataflow"
+ | "external-dependencies"
| "fileformat"
| "for-jupyter-users"
| "intro"
diff --git a/tests/_convert/markdown/snapshots/dataflow.md.txt b/tests/_convert/markdown/snapshots/dataflow.md.txt
index 985bfaf879..ad1b8cda8e 100644
--- a/tests/_convert/markdown/snapshots/dataflow.md.txt
+++ b/tests/_convert/markdown/snapshots/dataflow.md.txt
@@ -68,14 +68,12 @@ mo.accordion(
```
```python {.marimo}
-mo.md(
- f"""
- {mo.as_html(plot_wave(amplitude, period))}
+mo.md(f"""
+{mo.as_html(plot_wave(amplitude, period))}
- - `refs: {mo.refs()}`
- - `defs: {mo.defs()}`
- """
-)
+- `refs: {mo.refs()}`
+- `defs: {mo.defs()}`
+""")
```
```python {.marimo}
diff --git a/tests/_convert/markdown/snapshots/marimo_for_jupyter_users.md.txt b/tests/_convert/markdown/snapshots/marimo_for_jupyter_users.md.txt
index 99b62f37c6..6ad1fb4493 100644
--- a/tests/_convert/markdown/snapshots/marimo_for_jupyter_users.md.txt
+++ b/tests/_convert/markdown/snapshots/marimo_for_jupyter_users.md.txt
@@ -3,6 +3,12 @@ title: marimo for Jupyter users
marimo-version: 0.0.0
header: |-
# Copyright 2026 Marimo. All rights reserved.
+ # /// script
+ # requires-python = ">=3.12"
+ # dependencies = [
+ # "marimo",
+ # ]
+ # ///
---
# marimo for Jupyter users
@@ -27,7 +33,7 @@ y = x + 1; y
marimo 'reacts' to the change in `x` and automatically recalculates `y`!
**Explanation.** marimo reads the code in your cells and understands the
-dependences between them, based on the variables that each cell declares and
+dependencies between them, based on the variables that each cell declares and
references. When you execute one cell, marimo automatically executes all other
cells that depend on it, not unlike a spreadsheet.
@@ -141,11 +147,9 @@ ergonomics for authoring.
///
```python {.marimo}
-mo.md(
- f"""
- The value of {slider} is {slider.value}.
- """
-)
+mo.md(f"""
+The value of {slider} is {slider.value}.
+""")
```
**Explanation.** By lifting Markdown into Python, marimo lets you construct
diff --git a/tests/_convert/markdown/snapshots/sql.md.txt b/tests/_convert/markdown/snapshots/sql.md.txt
index 4f61f05738..ead6130741 100644
--- a/tests/_convert/markdown/snapshots/sql.md.txt
+++ b/tests/_convert/markdown/snapshots/sql.md.txt
@@ -7,9 +7,12 @@ header: |-
# /// script
# requires-python = ">=3.12"
# dependencies = [
+ # "altair==6.1.0",
# "duckdb==1.2.2",
# "marimo",
+ # "matplotlib==3.10.9",
# "pandas==2.2.3",
+ # "plotly==6.7.0",
# "polars==1.27.1",
# "pyarrow==19.0.1",
# "sqlglot==26.13.0",