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: debugging notebooks (#6305)

Dylan Madisetti7dc72ae3e1c0
diff --git a/docs/_static/docs-debugpy-edit-mode.webm b/docs/_static/docs-debugpy-edit-mode.webm
new file mode 100644
index 0000000000..70da66c0f1
Binary files /dev/null and b/docs/_static/docs-debugpy-edit-mode.webm differ
diff --git a/docs/_static/docs-notebook-errors-context.png b/docs/_static/docs-notebook-errors-context.png
new file mode 100644
index 0000000000..7faf7749ee
Binary files /dev/null and b/docs/_static/docs-notebook-errors-context.png differ
diff --git a/docs/_static/docs-pdb-breakpoint.webm b/docs/_static/docs-pdb-breakpoint.webm
new file mode 100644
index 0000000000..f4a854a0ce
Binary files /dev/null and b/docs/_static/docs-pdb-breakpoint.webm differ
diff --git a/docs/_static/docs-pdb-demo.png b/docs/_static/docs-pdb-demo.png
new file mode 100644
index 0000000000..c53a238d58
Binary files /dev/null and b/docs/_static/docs-pdb-demo.png differ
diff --git a/docs/_static/docs-postmortem-debugging.webm b/docs/_static/docs-postmortem-debugging.webm
new file mode 100644
index 0000000000..4a85e9ff29
Binary files /dev/null and b/docs/_static/docs-postmortem-debugging.webm differ
diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md
new file mode 100644
index 0000000000..3f6ef0e041
--- /dev/null
+++ b/docs/guides/debugging.md
@@ -0,0 +1,202 @@
+# Debugging marimo notebooks
+
+## Debugging in marimo
+
+### Using pdb in marimo notebooks
+
+marimo has direct support for pdb, the Python debugger. You can set breakpoints
+in your code using the built-in `breakpoint()` function. When the code
+execution reaches a breakpoint, it will pause, and you can inspect variables,
+step through the code, and evaluate expressions.
+
+Here's an example of how to use `breakpoint()` in a marimo notebook cell.
+
+![PDB in marimo](/_static/docs-pdb-demo.png)
+
+Type `help` in the debugger for a list of commands:
+
+```txt
+Documented commands (type help <topic>):
+========================================
+EOF cl disable ignore n return u where
+a clear display interact next retval unalias
+alias commands down j p run undisplay
+args condition enable jump pp rv unt
+b cont exceptions l q s until
+break continue exit list quit source up
+bt d h ll r step w
+c debug help longlist restart tbreak whatis
+
+Miscellaneous help topics:
+==========================
+exec pdb
+```
+
+!!! note
+ Since this block is runnable, you can test the debugger directly
+
+/// marimo-embed
+
+```python
+def _():
+ # Compute triangle numbers
+ triangle = 0
+ triangle_count = 20
+ for i in range(1, triangle_count):
+ triangle += i # T_i = sum of 1..i
+ # Debug at the 10th iteration
+ # as a sanity check. Should be 55.
+ if i == 10:
+ breakpoint()
+ return
+```
+
+///
+
+!!! tip
+ Click the little bug icon in the stack trace to add breakpoints.
+ <video autoplay muted loop playsinline width="100%" align="center" src="/_static/docs-pdb-breakpoint.webm" alt="Animation showing how to click the bug icon to add PDB breakpoints">
+ </video>
+ Clicking on the cell link will also take you to the cell where the error occurred.
+
+### Postmortem debugging
+
+If your code raises an exception, you can use postmortem debugging to inspect
+the state of the program at the point where the exception occurred. Click on
+the "Launch debugger" button as shown below:
+
+<video autoplay muted loop playsinline width="100%" align="center" src="/_static/docs-postmortem-debugging.webm" alt="Video demonstrating postmortem debugging with the Launch debugger button">
+</video>
+
+
+!!! note
+ Other tools like the following will also work in marimo notebooks:
+
+ ```python
+ import code
+ code.interact()
+ return
+ ```
+
+!!! danger
+ Remember to continue or quit the debugger to avoid hanging the notebook!
+
+## Tips for debugging marimo notebooks with AI
+
+marimo provides built-in integration with AI assistants to help debug your notebooks more effectively.
+
+### Ask about notebook errors
+
+When interacting with the AI chat, you can reference the notebook "Errors" with
+the `@-symbol` to bring in comprehensive error information from your notebook,
+making it easier to get targeted debugging help.
+
+![Notebook Errors context in marimo](/_static/docs-notebook-errors-context.png)
+
+### Best practices for AI-assisted debugging
+
+**Provide context beyond just the error.** Include information about:
+- What you were trying to accomplish
+- Recent changes you made to the notebook
+- Whether the error is new or recurring
+- Related cells that might be involved
+
+**Leverage marimo's debugging tools alongside AI.** Use marimo's [dataflow
+tools](../guides/troubleshooting.md#verify-cell-connections) to understand cell
+relationships, then share this information with AI assistants for more targeted
+advice.
+
+**Ask specific questions.** Instead of "Why is this broken?", try:
+- "Why might this reactivity issue be occurring between these cells?"
+- "How can I fix this import error in my marimo notebook?"
+- "What's the best way to debug this performance issue in my data processing pipeline?"
+
+!!! tip
+ AI assistants are particularly helpful for explaining marimo-specific
+ concepts like reactive execution, cell dependencies, and the differences
+ between marimo notebooks and traditional Jupyter notebooks.
+
+## Debugging notebooks as a script
+Since marimo notebooks are standard Python files, you can run them as scripts
+from the command line. The following command will run your marimo notebook and
+drop you into the pdb debugger if an exception occurs, or if you hit a
+breakpoint.
+
+```bash
+python -m pdb your_script.py
+```
+
+## External IDE debugging with `debugpy`
+
+marimo supports debugging with IDEs, like VSCode, which natively support the
+`debugpy` library. This allows you to set breakpoints, step through code, and
+inspect variables directly from your IDE.
+
+### Script mode
+You can debug marimo notebooks in VSCode using the following `launch.json`.
+This launch configuration will debug a marimo notebook in [script
+mode](./scripts.md).
+
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "python",
+ "request": "launch",
+ "name": "marimo Debug: script mode",
+ "program": "${file}",
+ "debugOptions": [
+ "--ignore", "*/site-packages/marimo/*"
+ ]
+ },
+ ]
+}
+```
+
+### Edit mode
+Edit mode debugging allows the marimo editor to trigger breakpoints set in an
+IDE like VSCode. Running in this mode will automatically start your notebook in
+[watch mode](./editor_features/watching.md). Note that the file state and
+editor must be consistent for break points to correctly work. If debugging is
+not acting as expected, force a notebook save and toggle the relevant
+breakpoints.
+
+Use the following `launch.json` configuration to enable edit mode debugging:
+
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "debugpy",
+ "request": "launch",
+ "name": "marimo Debug: edit mode",
+ "program": "${file}",
+ "console": "integratedTerminal",
+ "cwd": "${workspaceFolder}",
+ "env": {
+ "MARIMO_SCRIPT_EDIT": "1"
+ },
+ "justMyCode": false
+ }
+ ]
+}
+```
+
+<video autoplay muted loop playsinline width="100%" align="center" src="/_static/docs-debugpy-edit-mode.webm" alt="Video showing debugpy edit mode debugging with VSCode hitting marimo breakpoints">
+</video>
+
+!!! note
+ This will disable marimo's internal debugging features.
+
+!!! danger
+ This mode is blocking in VSCode, so you will need to interact with the
+ debugger in your editor to regain control of the marimo notebook.
+
+
+## Debug directly in VSCode
+
+!!! note
+ LSP support for marimo notebooks is coming soon, along with native debug server integration.
diff --git a/docs/guides/index.md b/docs/guides/index.md
index 83c9d89f9a..2b62548809 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -34,4 +34,5 @@ These guides cover marimo's core concepts.
| [Extending marimo](integrating_with_marimo/index.md) | Rich displays of objects, custom UI plugins |
| [State management](state.md) | Advanced: mutable reactive state |
| [Best practices](best_practices.md) | Best practices to help you get the most out of marimo |
+| [Debugging](debugging.md) | Interactive debugging with pdb, debugpy, and AI assistance |
| [Troubleshooting](troubleshooting.md) | Troubleshooting notebooks |
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 58cb8177a0..c3e6971ce3 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -6,7 +6,8 @@ define and reference. When things don't work as expected, marimo provides
interpretation of your notebook and debug issues.
This guide covers common issues and unexpected behaviors you might encounter,
-along with ways to debug and resolve them. If your issue isn't covered here,
+along with ways to debug and resolve them. For interactive debugging techniques,
+see our [debugging guide](debugging.md). If your issue isn't covered here,
try checking our [FAQ](../faq.md).
## Why aren't my cells running?
diff --git a/marimo/_smoke_tests/pdb_test.py b/marimo/_smoke_tests/pdb_test.py
index 6716c73813..6b1d45c82e 100644
--- a/marimo/_smoke_tests/pdb_test.py
+++ b/marimo/_smoke_tests/pdb_test.py
@@ -1,4 +1,4 @@
-# Copyright 2024 Marimo. All rights reserved.
+# Copyright 2025 Marimo. All rights reserved.
import marimo
@@ -9,52 +9,20 @@ app = marimo.App()
@app.cell
def _():
def percentile(xs, p):
- """
- Return the p-th percentile of xs.
- """
+ "Something with a bug"
xs = sorted(xs)
idx = round(p / 100 * len(xs)) # here there be bugs
return xs[idx]
-
-
- percentile([1, 2, 3], 100)
- return
-
-
-def _():
- # Compute triangle numbers
- triangle = 0
- triangle_count = 20
- for i in range(1, triangle_count):
- triangle += i # T_i = sum of 1..i
- # Debug at the 10th iteration
- # as a sanity check. Should be 55.
- if i == 10:
- breakpoint()
- return
-
-
-def _():
- import marimo as mo
+ # percentile([1, 2, 3], 100)
return
@app.cell
def _():
import pdb
-
pdb.set_trace()
return
-def _():
-
-
- return
-
-
if __name__ == "__main__":
app.run()