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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: polish tutorial notebooks (#9573)
Péter Gyarmatif924146dbac3
diff --git a/frontend/src/components/home/components.tsx b/frontend/src/components/home/components.tsxindex 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__.pyindex 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.pyindex 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.celldef _(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()}`+ """)returndiff --git a/marimo/_tutorials/external_dependencies.py b/marimo/_tutorials/external_dependencies.pynew file mode 100644index 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.pyindex 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 theirdefs (the global variables they define). The generated code makes thisanalogy 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 areits defs that are referenced by other cells.For example, the codediff --git a/marimo/_tutorials/for_jupyter_users.py b/marimo/_tutorials/for_jupyter_users.pyindex 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 andreferences. When you execute one cell, marimo automatically executes all othercells that depend on it, not unlike a spreadsheet.@@ -232,11 +238,9 @@ def _(mo):@app.celldef _(mo, slider):- mo.md(- f"""- The value of {slider} is {slider.value}.- """- )+ mo.md(f"""+ The value of {slider} is {slider.value}.+ """)returndiff --git a/marimo/_tutorials/intro.py b/marimo/_tutorials/intro.pyindex 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 alwaysconsistent, 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 changedelse 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 onthe 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. Thisfrees you to organize your code in the way that makes the mostsense 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 defaultvalues, 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).""")returndiff --git a/marimo/_tutorials/layout.py b/marimo/_tutorials/layout.pyindex 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 marimodiff --git a/marimo/_tutorials/markdown.py b/marimo/_tutorials/markdown.pyindex 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):```python3mo.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 valuesYou 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 createmarkdown whose contents depend on data that changes at runtime.Here are some examples.@@ -188,7 +188,9 @@ def _(mo):@app.celldef _(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.celldef _(amplitude, mo, period):- mo.md(- f"""+ mo.md(f"""**A sin curve.**- {amplitude}- {period}- """- )+ """)return@app.celldef _(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))}- """- )+ """)returndiff --git a/marimo/_tutorials/markdown_format.md b/marimo/_tutorials/markdown_format.mdindex 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.6author: Marimo Teamdescription: >-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 formatBy 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 Pythonvalues, 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 aspossible.<!---->### 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 inorder to specify column start and to save correctly:````md@@ -199,7 +202,7 @@ print("First cell in column 1")### Naming cellsSince 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 stillgive 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 notebookformat. 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 modiff --git a/marimo/_tutorials/plots.py b/marimo/_tutorials/plots.pyindex 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.pyindex 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.pyindex 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.celldef _(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.celldef _(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}+ """)returndiff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex 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- introdiff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex 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.txtindex 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.txtindex 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 usersmarimo-version: 0.0.0header: |-# Copyright 2026 Marimo. All rights reserved.+ # /// script+ # requires-python = ">=3.12"+ # dependencies = [+ # "marimo",+ # ]+ # ///---# marimo for Jupyter users@@ -27,7 +33,7 @@ y = x + 1; ymarimo '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 andreferences. When you execute one cell, marimo automatically executes all othercells 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 constructdiff --git a/tests/_convert/markdown/snapshots/sql.md.txt b/tests/_convert/markdown/snapshots/sql.md.txtindex 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",