+
-## Avoid mutating variables
+### Variable mutations are not tracked
-marimo's reactive execution is based only on the global variables a cell reads
-and the global variables it defines. In particular, _marimo does not track
-mutations to objects_, _i.e._, mutations don't trigger reactive re-runs of
-other cells. It also does not track the definition or mutation of object
-attributes. For this reason, **avoid defining a variable in one cell and
+marimo does not track mutations to objects, _e.g._, mutations like
+`my_list.append(42)` or `my_object.value = 42` don't trigger reactive re-runs of
+other cells. **Avoid defining a variable in one cell and
mutating it in another**.
+??? note "Why not track mutations?"
+
+ Tracking mutations reliably is impossible in Python. Reacting to mutations
+ could result in surprising re-runs of notebook cells.
+
If you need to mutate a variable (such as adding a new column to a dataframe),
you should perform the mutation in the same cell as the one that defines it,
-Or try creating a new variable instead.
+or try creating a new variable instead.
-### Examples
+??? example "Create new variables, don't mutate existing ones"
-**Create a new variable instead of mutating an existing one.**
+ === "Do this ..."
-_Don't_ do this:
+ ```python
+ l = [1]
+ ```
-```python
-l = [1]
-```
+ ```python
+ extended_list = l + [2]
+ ```
-```python
-l.append(2)
-```
+ === "... not this"
-_Instead_, do this:
+ ```python
+ l = [1]
+ ```
-```python
-l = [1]
-```
+ ```python
+ l.append(2)
+ ```
-```python
-extended_list = l + [2]
-```
+??? example "Mutate variables in the cells that define them"
-**Mutate variables in the cells that define them.**
+ === "Do this ..."
-_Don't_ do this:
+ ```python
+ df = pd.DataFrame({"my_column": [1, 2]})
+ df["another_column"] = [3, 4]
+ ```
-```python
-df = pd.DataFrame({"my_column": [1, 2]})
-```
-```python
-df["another_column"] = [3, 4]
-```
+ === "... not this"
+
+ ```python
+ df = pd.DataFrame({"my_column": [1, 2]})
+ ```
-_Instead_, do this:
+ ```python
+ df["another_column"] = [3, 4]
+ ```
+
+
+## Global variable names must be unique
+
+**marimo requires that every global variable be defined by only one cell.**
+This lets marimo keep code and outputs consistent.
+
+!!! tip "Global variables"
+ A variable can refer to any Python object. Functions, classes, and imported
+ names are all variables.
+
+
+This rule encourages you to keep the number of global variables in your
+program small, which is generally considered good practice.
+
+### Creating temporary variables
+
+marimo provides two ways to define temporary variables, which can
+help keep the number of global variables in your notebook small.
+
+#### Creating local variables
+
+Variables prefixed with an underscore (_e.g._, `_x`) are "local" to a
+cell: they can't be read by other cells. Multiple cells can reuse the same
+local variables names.
+
+#### Encapsulating code in functions
+
+If you want most or all the variables in a cell to be temporary, prefixing each
+variable with an underscore to make it local may feel inconvenient. In these
+situations we recommend encapsulating the temporary variables in a function.
+
+For example, if you find yourself copy-pasting the same plotting code across
+multiple cells and only tweaking a few parameters, try the following pattern:
```python
-df = pd.DataFrame({"my_column": [1, 2]})
-df["another_column"] = [3, 4]
+def _():
+ import matplotlib.pyplot as plt
+ fig, ax = plt.subplots()
+ ax.plot([1, 2])
+ return ax
+
+_()
```
-!!! note "Why not track mutations?"
- Tracking mutations reliably is a fundamentally impossible task in Python; marimo
- could never detect all mutations, and even if we could, reacting to mutations could
- result in surprising re-runs of notebook cells. The simplicity of marimo's
- static analysis approach, based only on variable definitions and references,
- makes marimo easy to understand and encourages well-organized notebook code.
+Here, the variables `plt`, `fig`, and `ax` aren't added to the globals.
+
-## Runtime configuration
+## Configuring how marimo runs cells
Through the notebook settings menu, you can configure how and when marimo runs
cells. In particular, you can disable autorun on startup, disable autorun
-on cell execution, and enable a powerful module autoreloader. Read our
+on cell execution, and enable a module autoreloader. Read our
[runtime configuration guide](configuration/runtime_configuration.md) to learn more.
## Disabling cells
diff --git a/mkdocs.yml b/mkdocs.yml
index a2cc76fba4f..13493f789f4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -58,6 +58,8 @@ markdown_extensions:
custom_fences:
- class: mermaid
name: mermaid
+ - pymdownx.tabbed:
+ alternate_style: true
- pymdownx.blocks.tab:
alternate_style: true
- pymdownx.tasklist:
@@ -74,7 +76,7 @@ nav:
- User Guide:
- Overview: guides/index.md
- - Reactive execution: guides/reactivity.md
+ - Running cells: guides/reactivity.md
- Interactive elements: guides/interactivity.md
- Visualizing outputs: guides/outputs.md
- Migrating from Jupyter: guides/coming_from/jupyter.md