tools-only App API Reference
Work with marimo notebooks programmatically, embed notebooks, and access runtime metadata.
App Class
marimo.App
Represents a marimo notebook as a dataflow graph.
import marimo
# In a notebook file
app = marimo.App()
@app.cell
def _():
x = 42
return (x,)
@app.cell
def _(x):
result = x * 2
return (result,)
if __name__ == "__main__":
app.run()
Embedding Notebooks
app.embed
Embed one notebook's output into another (async).
import marimo as mo
# Import another notebook
from other_notebook import app as other_app
# Embed it
async def embed_notebook():
result = await other_app.embed()
return result.output
# In a cell
output = await other_app.embed()
output.output # Visual output
output.defs # Variable definitions
With parameter override:
# Override definitions in embedded notebook
result = await other_app.embed(defs={"threshold": 0.8})
# The embedded notebook runs with threshold=0.8
# instead of its default value
Nested Embedding
Notebooks can be nested multiple levels:
# notebook_a.py embeds notebook_b.py
# notebook_b.py embeds notebook_c.py
# All work correctly with reactive updates
Interactive Embedded Notebooks
When embedded notebooks contain UI elements, interactions trigger updates:
# other_notebook.py defines a slider
# When embedded, slider interactions update the parent notebook
result = await other_app.embed()
result.output # Contains interactive slider
# Slider changes propagate reactively
Running Programmatically
app.run
Execute a notebook and get outputs.
from my_notebook import app
# Run the notebook
outputs, definitions = app.run()
# outputs: Sequence of cell outputs
# definitions: Mapping of variable names to values
print(definitions["result"]) # Access computed value
With definition overrides:
# Override input values
outputs, definitions = app.run(defs={
"input_data": my_data,
"config": my_config
})
# Cells defining input_data and config are skipped
# Their dependents run with the provided values
App Metadata
mo.app_meta
Access runtime information about the current app.
import marimo as mo
meta = mo.app_meta()
Properties
mode: Execution context.
mode = mo.app_meta().mode
# Possible values:
# - "edit": Running in marimo editor
# - "run": Running as app (marimo run)
# - "script": Running as Python script
# - "test": Running in pytest
# - None: Unknown context
theme: Current display theme.
theme = mo.app_meta().theme
# Possible values:
# - "light"
# - "dark"
request: HTTP request data (in app mode).
request = mo.app_meta().request
# Access request information
request.headers # HTTP headers
request.cookies # Cookies
request.query_params # URL query parameters
request.user # Authenticated user info (if available)
Conditional Behavior
Based on Mode
mode = mo.app_meta().mode
if mode == "edit":
# Show debug information
mo.output.append(f"Debug: {debug_data}")
elif mode == "run":
# Production app behavior
pass
elif mode == "script":
# Script execution
print("Running as script")
Based on Theme
theme = mo.app_meta().theme
# Adapt visualization colors
if theme == "dark":
bg_color = "#1a1a1a"
text_color = "#ffffff"
else:
bg_color = "#ffffff"
text_color = "#000000"
# Use in plots
import matplotlib.pyplot as plt
plt.style.use("dark_background" if theme == "dark" else "default")
Based on User
request = mo.app_meta().request
if request and request.user:
user_name = request.user.get("name", "Guest")
mo.md(f"Welcome, {user_name}!")
else:
mo.md("Please log in")
Notebook as Module
Import and use notebooks as Python modules:
# utils_notebook.py defines utility functions
from utils_notebook import process_data, validate_input
# Use exported functions
result = process_data(my_data)
Cells can be imported individually:
from utils_notebook import calculate
# Run the cell
output, defs = calculate.run()
result = defs["result"]
Testing Notebooks
# test_notebook.py
import pytest
from my_notebook import app, process_cell
def test_process_cell():
output, defs = process_cell.run(input_data=[1, 2, 3])
assert defs["result"] == [2, 4, 6]
def test_full_notebook():
outputs, defs = app.run(defs={"test_mode": True})
assert defs["final_result"] is not None
Best Practices
Design for Embedding
# Good - notebook has clear inputs and outputs
@app.cell
def _(input_data, config): # Clear inputs
result = process(input_data, config)
return (result,) # Clear output
# Avoid - hidden dependencies
@app.cell
def _():
global_var = something # Hard to override
Check Mode Before UI
mode = mo.app_meta().mode
if mode == "script":
# Use CLI args or defaults
threshold = mo.cli_args().get("threshold", 0.5)
else:
# Show interactive UI
threshold = mo.ui.slider(0, 1, value=0.5).value
Handle Missing Request
request = mo.app_meta().request
# Always check for None
if request is not None:
user = request.user
else:
user = None
Export Clean APIs
# In notebook, define clean interface
@app.cell
def _():
def public_function(data):
"""Process data and return results."""
return _internal_process(data)
return (public_function,)
# Other notebooks can import and use
from my_notebook import public_function