marimo https://docs.marimo.io marimo is an [open-source](https://github.com/marimo-team/marimo) reactive Python notebook: run a cell or interact with a UI element, and marimo automatically runs dependent cells (or [marks them as stale](https://docs.marimo.io/guides/reactivity/#configuring-how-marimo-runs-cells)), keeping code and outputs consistent and preventing bugs before they happen. Every marimo notebook is stored as pure Python (Git-friendly), executable as a script, and deployable as an app; while stored as Python, marimo notebooks also have native support for SQL. install with pipinstall with uvinstall with conda `[](#__codelineno-0-1)pip install marimo && marimo tutorial intro` `[](#__codelineno-1-1)uv add marimo && uv run marimo tutorial intro` `[](#__codelineno-2-1)conda install -c conda-forge marimo && marimo tutorial intro` Developer experience is core to marimo, with an emphasis on reproducibility, maintainability, composability, and shareability. Highlights[¶](#highlights "Permanent link") ------------------------------------------- * 🚀 **batteries-included:** replaces `jupyter`, `streamlit`, `jupytext`, `ipywidgets`, `papermill`, and more * ⚡️ **reactive**: run a cell, and marimo reactively [runs all dependent cells](https://docs.marimo.io/guides/reactivity/) or [marks them as stale](#expensive-notebooks) * 🖐️ **interactive:** [bind sliders, tables, plots, and more](https://docs.marimo.io/guides/interactivity/) to Python — no callbacks required * 🐍 **git-friendly:** stored as `.py` files * 🛢️ **designed for data**: query dataframes, databases, warehouses, and lakehouses [with SQL](https://docs.marimo.io/guides/working_with_data/sql/); filter and search [dataframes](https://docs.marimo.io/guides/working_with_data/dataframes/) * 🤖 **AI-native**: [generate cells with AI](https://docs.marimo.io/guides/generate_with_ai/) tailored for data work * 🔬 **reproducible:** [no hidden state](https://docs.marimo.io/guides/reactivity/), deterministic execution, [built-in package management](https://docs.marimo.io/guides/editor_features/package_management/) * 🏃 **executable:** [execute as a Python script](https://docs.marimo.io/guides/scripts/), parameterized by CLI args * 🛜 **shareable**: [deploy as an interactive web app](https://docs.marimo.io/guides/apps/) or [slides](https://docs.marimo.io/guides/apps/#slides-layout), [run in the browser via WASM](https://docs.marimo.io/guides/wasm/) * 🧩 **reusable:** [import functions and classes](https://docs.marimo.io/guides/reusing_functions/) from one notebook to another * 🧪 **testable:** [run pytest](https://docs.marimo.io/guides/testing/) on notebooks * ⌨️ **a modern editor**: [GitHub Copilot](https://docs.marimo.io/guides/editor_features/ai_completion/#github-copilot), [AI assistants](https://docs.marimo.io/guides/editor_features/ai_completion/), vim keybindings, variable explorer, and [more](https://docs.marimo.io/guides/editor_features/) A reactive programming environment[¶](#a-reactive-programming-environment "Permanent link") ------------------------------------------------------------------------------------------- marimo guarantees your notebook code, outputs, and program state are consistent. This [solves many problems](https://docs.marimo.io/faq/#faq-problems) associated with traditional notebooks like Jupyter. **A reactive programming environment.** Run a cell and marimo _reacts_ by automatically running the cells that reference its variables, eliminating the error-prone task of manually re-running cells. Delete a cell and marimo scrubs its variables from program memory, eliminating hidden state. **Compatible with expensive notebooks.** marimo lets you [configure the runtime to be lazy](https://docs.marimo.io/guides/configuration/runtime_configuration/), marking affected cells as stale instead of automatically running them. This gives you guarantees on program state while preventing accidental execution of expensive cells. **Synchronized UI elements.** Interact with [UI elements](https://docs.marimo.io/guides/interactivity/) like [sliders](https://docs.marimo.io/api/inputs/slider/#slider), [dropdowns](https://docs.marimo.io/api/inputs/dropdown/), [dataframe transformers](https://docs.marimo.io/api/inputs/dataframe/), and [chat interfaces](https://docs.marimo.io/api/inputs/chat/), and the cells that use them are automatically re-run with their latest values. **Interactive dataframes.** [Page through, search, filter, and sort](https://docs.marimo.io/guides/working_with_data/dataframes/) millions of rows blazingly fast, no code required. **Generate cells with data-aware AI.** [Generate code with an AI assistant](https://docs.marimo.io/guides/editor_features/ai_completion/) that is highly specialized for working with data, with context about your variables in memory; [zero-shot entire notebooks](https://docs.marimo.io/guides/generate_with_ai/text_to_notebook/). Customize the system prompt, bring your own API keys, or use local models. **Query data with SQL.** Build [SQL](https://docs.marimo.io/guides/working_with_data/sql.html) queries that depend on Python values and execute them against dataframes, databases, lakehouses, CSVs, Google Sheets, or anything else using our built-in SQL engine, which returns the result as a Python dataframe. Your notebooks are still pure Python, even if they use SQL. **Dynamic markdown.** Use markdown parametrized by Python variables to tell dynamic stories that depend on Python data. **Built-in package management.** marimo has built-in support for all major package managers, letting you [install packages on import](https://docs.marimo.io/guides/editor_features/package_management/). marimo can even [serialize package requirements](https://docs.marimo.io/guides/package_management/inlining_dependencies/) in notebook files, and auto install them in isolated venv sandboxes. **Deterministic execution order.** Notebooks are executed in a deterministic order, based on variable references instead of cells' positions on the page. Organize your notebooks to best fit the stories you'd like to tell. **Performant runtime.** marimo runs only those cells that need to be run by statically analyzing your code. **Batteries-included.** marimo comes with GitHub Copilot, AI assistants, Ruff code formatting, HTML export, fast code completion, a [VS Code extension](https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo), an interactive dataframe viewer, and [many more](https://docs.marimo.io/guides/editor_features/) quality-of-life features. Quickstart[¶](#quickstart "Permanent link") ------------------------------------------- _The [marimo concepts playlist](https://www.youtube.com/watch?v=3N6lInzq5MI&list=PLNJXGo8e1XT9jP7gPbRdm1XwloZVFvLEq) on our [YouTube channel](https://www.youtube.com/@marimo-team) gives an overview of many features._ **Installation.** In a terminal, run `[](#__codelineno-3-1)pip install marimo # or conda install -c conda-forge marimo [](#__codelineno-3-2)marimo tutorial intro` To install with additional dependencies that unlock SQL cells, AI completion, and more, run `[](#__codelineno-4-1)pip install marimo[recommended]` **Create notebooks.** Create or edit notebooks with **Run apps.** Run your notebook as a web app, with Python code hidden and uneditable: `[](#__codelineno-6-1)marimo run your_notebook.py` **Execute as scripts.** Execute a notebook as a script at the command line: **Automatically convert Jupyter notebooks.** Automatically convert Jupyter notebooks to marimo notebooks with the CLI `[](#__codelineno-8-1)marimo convert your_notebook.ipynb > your_notebook.py` or use our [web interface](https://marimo.io/convert). **Tutorials.** List all tutorials: **Share cloud-based notebooks.** Use [molab](https://molab.marimo.io/notebooks), a cloud-based marimo notebook service similar to Google Colab, to create and share notebook links. Questions?[¶](#questions "Permanent link") ------------------------------------------ See our [FAQ](https://docs.marimo.io/faq/). Learn more[¶](#learn-more "Permanent link") ------------------------------------------- marimo is easy to get started with, with lots of room for power users. For example, here's an embedding visualizer made in marimo ([video](https://marimo.io/videos/landing/full.mp4)): Check out our [guides](https://docs.marimo.io/guides/), [usage examples](https://docs.marimo.io/examples/), and our [gallery](https://marimo.io/gallery) to learn more.
TutorialInputsPlotsLayout
Contributing[¶](#contributing "Permanent link") ----------------------------------------------- We appreciate all contributions! You don't need to be an expert to help out. Please see [CONTRIBUTING.md](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md) for more details on how to get started. > Questions? Reach out to us [on Discord](https://marimo.io/discord?ref=docs). We're building a community. Come hang out with us! * 🌟 [Star us on GitHub](https://github.com/marimo-team/marimo) * 💬 [Chat with us on Discord](https://marimo.io/discord?ref=docs) * 📧 [Subscribe to our Newsletter](https://marimo.io/newsletter) * ☁️ [Join our Cloud Waitlist](https://marimo.io/cloud) * ✏️ [Start a GitHub Discussion](https://github.com/marimo-team/marimo/discussions) * 💬 [Follow us on Bluesky](https://bsky.app/profile/marimo.io) * 🐦 [Follow us on Twitter](https://twitter.com/marimo_io) * 🎥 [Subscribe on YouTube](https://www.youtube.com/@marimo-team) * 💬 [Follow us on Mastodon](https://mastodon.social/@marimo_io) * 🕴️ [Follow us on LinkedIn](https://www.linkedin.com/company/marimo-io) **A NumFOCUS affiliated project.** marimo is a core part of the broader Python ecosystem and is a member of the NumFOCUS community, which includes projects such as NumPy, SciPy, and Matplotlib. Inspiration ✨[¶](#inspiration "Permanent link") ----------------------------------------------- marimo is a **reinvention** of the Python notebook as a reproducible, interactive, and shareable Python program, instead of an error-prone JSON scratchpad. We believe that the tools we use shape the way we think — better tools, for better minds. With marimo, we hope to provide the Python community with a better programming environment to do research and communicate it; to experiment with code and share it; to learn computational science and teach it. Our inspiration comes from many places and projects, especially [Pluto.jl](https://github.com/fonsp/Pluto.jl), [ObservableHQ](https://observablehq.com/tutorials), and [Bret Victor's essays](http://worrydream.com/). marimo is part of a greater movement toward reactive dataflow programming. From [IPyflow](https://github.com/ipyflow/ipyflow), [streamlit](https://github.com/streamlit/streamlit), [TensorFlow](https://github.com/tensorflow/tensorflow), [PyTorch](https://github.com/pytorch/pytorch/tree/main), [JAX](https://github.com/google/jax), and [React](https://github.com/facebook/react), the ideas of functional, declarative, and reactive programming are transforming a broad range of tools for the better. Getting Started - marimo https://docs.marimo.io/getting_started/ These tutorials will help you get started with marimo | Guide | Description | | --- | --- | | [Installation](https://docs.marimo.io/getting_started/installation/) | Installing marimo | | [Quickstart](https://docs.marimo.io/getting_started/quickstart/) | Create notebooks, run apps, and more from the marimo command-line | | [Key Concepts](https://docs.marimo.io/getting_started/key_concepts/) | A tour of key features and concepts | Examples - marimo https://docs.marimo.io/examples/ This page includes dozens of bite-sized how-to examples to help you get started with marimo. Be sure to also read the [quickstart](https://docs.marimo.io/getting_started/) and the [user guide](https://docs.marimo.io/guides/), especially the guide on [how marimo runs cells](https://docs.marimo.io/guides/reactivity/). Get inspired at our gallery! For inspirational examples, including embedding-driven data labelers, Stanford-scientist authored tutorials, and more, check out our [public gallery](https://marimo.io/gallery). Running cells[¶](#running-cells "Permanent link") ------------------------------------------------- * ⚡️ [**Basic execution**](https://docs.marimo.io/examples/running_cells/basics/) * 🐞 [**Getting around multiple definition errors**](https://docs.marimo.io/examples/running_cells/multiple_definitions/) * 🛑 [**Stop cells from running**](https://docs.marimo.io/examples/running_cells/stop/) * 🖱️ [**Run cells on button click**](https://docs.marimo.io/examples/running_cells/run_button/) * 🕓 [**Refresh on a timer**](https://docs.marimo.io/examples/running_cells/refresh/) * ⏳ [**Run async functions**](https://docs.marimo.io/examples/running_cells/async_await/) * 💾 [**Caching computations in memory**](https://docs.marimo.io/examples/running_cells/memory_cache/) * 💾 [**Cache computations to persistent storage**](https://docs.marimo.io/examples/running_cells/persistent_cache/) * 🐞 [**Using the debugger**](https://docs.marimo.io/examples/running_cells/debugging/) * 🐍 [**Run notebooks as scripts**](https://docs.marimo.io/guides/scripts/) Visual Outputs[¶](#visual-outputs "Permanent link") --------------------------------------------------- * 📤 [**Cell outputs**](https://docs.marimo.io/examples/outputs/basic_output/) * ✍️ [**Basic markdown**](https://docs.marimo.io/examples/outputs/basic_markdown/) * 💬 [**Console outputs**](https://docs.marimo.io/examples/outputs/console_outputs/) * 📋 [**Capturing console output**](https://docs.marimo.io/examples/outputs/capture_console_outputs/) * 📈 [**Showing plots**](https://docs.marimo.io/examples/outputs/plots/) * 🎥 [**Showing videos and other media**](https://docs.marimo.io/api/media/) * 🎛️ [**Conditionally showing outputs**](https://docs.marimo.io/examples/outputs/conditional_output/) * 🧩 [**Showing multiple outputs in one cell**](https://docs.marimo.io/examples/outputs/multiple_outputs/) ### Writing markdown[¶](#writing-markdown "Permanent link") * ⚡️ [**Python values in markdown**](https://docs.marimo.io/examples/markdown/dynamic_markdown/) * * * * 🪄 [**Mermaid diagrams**](https://docs.marimo.io/examples/markdown/mermaid/) * * * * 🚨 [**Admonitions**](https://docs.marimo.io/examples/markdown/admonitions/) * * * * 📂 [**Collapsible details**](https://docs.marimo.io/examples/markdown/details/) * * * * 😀 [**Emoji**](https://docs.marimo.io/examples/markdown/emoji/) Working with data[¶](#working-with-data "Permanent link") --------------------------------------------------------- ### Dataframes[¶](#dataframes "Permanent link") marimo is designed for working with dataframes. Here are a few examples; see the [dataframes guide](https://docs.marimo.io/guides/working_with_data/dataframes/) for details. * 🧮 [**Interactive dataframe viewer**](https://docs.marimo.io/examples/outputs/dataframes/) * * * * 🔍 [**Select dataframe rows**](https://docs.marimo.io/api/inputs/table/) * * * * ✏️ [**Editable dataframe**](https://docs.marimo.io/api/inputs/data_editor/) * * * * 🛠️ [**Interactive dataframe transformer**](https://docs.marimo.io/api/inputs/dataframe/) * * * ### SQL[¶](#sql "Permanent link") Here are some basic examples, see the [SQL guide](https://docs.marimo.io/guides/working_with_data/sql/) for more details. * 🦆 [**Query dataframes with DuckDB SQL**](https://docs.marimo.io/guides/working_with_data/sql/#example) * 🛢️ [**SQLite, Postgres, and other engines**](https://docs.marimo.io/guides/working_with_data/sql/#connecting-to-a-custom-database) ### Plots[¶](#plots "Permanent link") See the [plotting guide](https://docs.marimo.io/guides/working_with_data/plotting/) for a full overview. * 📊 [**Selecting data with Altair**](https://docs.marimo.io/api/plotting/#reactive-charts-with-altair) * * * * 📉 [**Selecting data with Plotly**](https://docs.marimo.io/guides/working_with_data/plotting/#plotly) * * * * 🔭 [**Showing matplotlib plots**](https://docs.marimo.io/examples/outputs/plots/) ### Progress bars and status elements[¶](#progress-bars-and-status-elements "Permanent link") * 📶 [**Progress bar**](https://docs.marimo.io/examples/outputs/progress_bar/) * * * * 🌀 [**Loading spinner**](https://docs.marimo.io/examples/outputs/spinner/) * * * ### Layouts[¶](#layouts "Permanent link") * 📐 [**Horizontal and vertical stacking**](https://docs.marimo.io/examples/outputs/stacks/) * * * * 📁 [**Accordion toggle**](https://docs.marimo.io/api/layouts/accordion/) * * * * 🗂️ [**Tabs**](https://docs.marimo.io/api/inputs/tabs/) * * * Input elements[¶](#input-elements "Permanent link") --------------------------------------------------- ### Basic input elements[¶](#basic-input-elements "Permanent link") marimo has a large library of interactive UI elements, which you can use without callbacks — just make sure to assign elements to global variables. See the [API reference](https://docs.marimo.io/api/inputs/) for a full list, and the [interactivity guide](https://docs.marimo.io/guides/interactivity/) for rules governing how UI elements work. * 🎚️ [**Slider**](https://docs.marimo.io/api/inputs/slider/) * * * * 🧾 [**Dropdown**](https://docs.marimo.io/api/inputs/dropdown/) * * * * 👆 [**Multi-select**](https://docs.marimo.io/api/inputs/multiselect/) * * * * 🔘 [**Radio buttons**](https://docs.marimo.io/api/inputs/radio/) * * * * ☑️ [**Checkbox**](https://docs.marimo.io/api/inputs/checkbox/) * * * * 📅 [**Date**](https://docs.marimo.io/api/inputs/dates/) * * * * 📁 [**File**](https://docs.marimo.io/api/inputs/file/) * * * * 🔤 [**Text input**](https://docs.marimo.io/api/inputs/text/) * * * * 📝 [**Text area**](https://docs.marimo.io/api/inputs/text_area/) * * * * 🧑‍💻 [**Code editor**](https://docs.marimo.io/api/inputs/code_editor/) * * * * 🔍 [**Table**](https://docs.marimo.io/api/inputs/table/) * * * * 🎙️ [**Microphone**](https://docs.marimo.io/api/inputs/microphone/) * * * * 💬 [**Chat**](https://docs.marimo.io/api/inputs/chat/) * * * ### Composite input elements[¶](#composite-input-elements "Permanent link") Composite input elements let you create a single UI element from multiple other UI elements. * 🧾 [**Form**](https://docs.marimo.io/api/inputs/form/) * * * * 🎒 [**Array**](https://docs.marimo.io/api/inputs/array/) * * * * 📖 [**Dictionary**](https://docs.marimo.io/api/inputs/dictionary/) * * * User Guide - marimo https://docs.marimo.io/guides/ Guides[¶](#guides "Permanent link") ----------------------------------- These guides cover marimo's core concepts. Learn by doing! Prefer a hands-on learning experience? marimo comes packaged with interactive tutorials that you can launch with `marimo tutorial` at the command line. | Guide | Description | | --- | --- | | [Running cells](https://docs.marimo.io/guides/reactivity/) | Understanding how marimo runs cells | | [Interactive elements](https://docs.marimo.io/guides/interactivity/) | Using interactive UI elements | | [Visualizing outputs](https://docs.marimo.io/guides/outputs/) | Creating markdown, plots, and other visual outputs | | [Migrating from Jupyter](https://docs.marimo.io/guides/coming_from/jupyter/) | Tips for transitioning from Jupyter | | [Expensive notebooks](https://docs.marimo.io/guides/expensive_notebooks/) | Tips for working with expensive notebooks | | [Understanding errors](https://docs.marimo.io/guides/understanding_errors/) | Understanding marimo's constraints on notebook code | | [Lint rules](https://docs.marimo.io/guides/lint_rules/) | Comprehensive linting system and rule reference | | [Working with data](https://docs.marimo.io/guides/working_with_data/) | Using SQL cells, no-code dataframe, and reactive plots | | [Package management](https://docs.marimo.io/guides/package_management/) | Inlining dependencies in notebook files and other package management guides | | [Generate with AI](https://docs.marimo.io/guides/generate_with_ai/) | Generate notebooks with AI | | [Editor features](https://docs.marimo.io/guides/editor_features/) | View variables, dataframe schemas, docstrings, and more | | [Using your own editor](https://docs.marimo.io/guides/editor_features/watching/) | Edit notebooks in your own editor and stream changes back to the browser | | [Apps](https://docs.marimo.io/guides/apps/) | Running notebooks as apps | | [Scripts](https://docs.marimo.io/guides/scripts/) | Running notebooks as scripts | | [Reusing functions and classes](https://docs.marimo.io/guides/reusing_functions/) | Importing functions and classes defined in marimo notebooks | | [Tests](https://docs.marimo.io/guides/testing/) | Running unit tests in notebooks | | [Export notebooks](https://docs.marimo.io/guides/exporting/) | Exporting notebooks to HTML, ipynb, flat scripts, and more | | [Cloud notebooks with molab](https://docs.marimo.io/guides/molab/) | Share links to cloud-based marimo notebooks, similar to Google Colab | | [Publish to the web](https://docs.marimo.io/guides/publishing/) | Edit and publish notebooks on the web | | [Run notebooks with WebAssembly](https://docs.marimo.io/guides/wasm/) | Create notebooks in our online playground | | [Deploying](https://docs.marimo.io/guides/deploying/) | Deploying marimo notebooks and apps | | [Configuration](https://docs.marimo.io/guides/configuration/) | Configure various settings | | [Coming from other tools](https://docs.marimo.io/guides/coming_from/) | Transitioning from Jupyter and other tools | | [Extending marimo](https://docs.marimo.io/guides/integrating_with_marimo/) | Rich displays of objects, custom UI plugins | | [State management](https://docs.marimo.io/guides/state/) | Advanced: mutable reactive state | | [Best practices](https://docs.marimo.io/guides/best_practices/) | Best practices to help you get the most out of marimo | | [Debugging](https://docs.marimo.io/guides/debugging/) | Interactive debugging with pdb, debugpy, and AI assistance | | [Troubleshooting](https://docs.marimo.io/guides/troubleshooting/) | Troubleshooting notebooks | API Reference - marimo https://docs.marimo.io/api/ Use the marimo library in marimo notebooks (`import marimo as mo`) to * connect interactive inputs like sliders, dropdowns, and tables to Python, * express yourself with dynamically created markdown, * layout information with tabs or grids, * output media like images and audio, * and more! | | | | --- | --- | | [markdown](https://docs.marimo.io/api/markdown/) | Write markdown with `mo.md` | | [inputs](https://docs.marimo.io/api/inputs/) | Connect sliders, dropdowns, tables, and more to Python | | [layouts](https://docs.marimo.io/api/layouts/) | Customize outputs with accordions, tabs, stacks, and more | | [plotting](https://docs.marimo.io/api/plotting/) | Output interactive plots | | [media](https://docs.marimo.io/api/media/) | Output media like images, audio, PDFs, and plain text | | [diagrams](https://docs.marimo.io/api/diagrams/) | Flow charts, graphs, statistic cards, and more | | [status](https://docs.marimo.io/api/status/) | Display progress indicators | | [outputs](https://docs.marimo.io/api/outputs/) | Modify cell outputs, redirect console output | | [control\_flow](https://docs.marimo.io/api/control_flow/) | Control how cells execute | | [html](https://docs.marimo.io/api/html/) | Manipulate HTML objects | | [query\_params](https://docs.marimo.io/api/query_params/) | Access and set query parameters with `mo.query_params` | | [cli\_args](https://docs.marimo.io/api/cli_args/) | Access command-line arguments with `mo.cli_args` | | [caching](https://docs.marimo.io/api/caching/) | Cache expensive computations in memory or on disk | | [state](https://docs.marimo.io/api/state/) | Synchronize multiple UI elements with `mo.state` | | [app](https://docs.marimo.io/api/app/) | Embed notebooks in other notebooks | | [cell](https://docs.marimo.io/api/cell/) | Run cells defined in another notebook | | [watch](https://docs.marimo.io/api/watch/) | Reactively respond to file changes on disk | | [miscellaneous](https://docs.marimo.io/api/miscellaneous/) | Miscellaneous utilities | Commands - marimo https://docs.marimo.io/cli/ Welcome to marimo! Getting started: * marimo tutorial intro Example usage: * marimo edit create or edit notebooks * marimo edit notebook.py create or edit a notebook called notebook.py * marimo run notebook.py run a notebook as a read-only app * marimo tutorial --help list tutorials **Usage:** `[](#__codelineno-0-1)marimo [OPTIONS] COMMAND [ARGS]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--version` | boolean | Show the version and exit. | `False` | | `-l`, `--log-level` | choice (`DEBUG` | `INFO` | `WARN` | `ERROR` | `CRITICAL`) | Choose logging level. | `WARN` | | `-q`, `--quiet` | boolean | Suppress standard out. | `False` | | `-y`, `--yes` | boolean | Automatic yes to prompts, running non-interactively. | `False` | | `-d`, `--development-mode` | boolean | Run in development mode; enables debug logs and server autoreload. | `False` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo check[¶](#marimo-check "Permanent link") ----------------------------------------------- Check and format marimo files. **Usage:** `[](#__codelineno-1-1)marimo check [OPTIONS] [FILES]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--fix` | boolean | Whether to in place update files. | `False` | | `--strict` | boolean | Whether warnings return a non-zero exit code. | `False` | | `-v`, `--verbose` / `-q`, `--quiet` | boolean | Whether to print detailed messages. | `True` | | `--unsafe-fixes` | boolean | Enable fixes that may change code behavior (e.g., removing empty cells). | `False` | | `--ignore-scripts` | boolean | Ignore files that are not recognizable as marimo notebooks. | `False` | | `--format` | choice (`full` | `json`) | Output format for diagnostics. | `full` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo config[¶](#marimo-config "Permanent link") ------------------------------------------------- Various commands for the marimo config. **Usage:** `[](#__codelineno-2-1)marimo config [OPTIONS] COMMAND [ARGS]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo config describe[¶](#marimo-config-describe "Permanent link") Describe the marimo config. **Usage:** `[](#__codelineno-3-1)marimo config describe [OPTIONS]` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo config show[¶](#marimo-config-show "Permanent link") Show the marimo config. **Usage:** `[](#__codelineno-4-1)marimo config show [OPTIONS]` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo convert[¶](#marimo-convert "Permanent link") --------------------------------------------------- Convert a Jupyter notebook, Markdown file, or Python script to a marimo notebook. Supported input formats: - `.ipynb` (local or GitHub-hosted) - `.md` files with `{python}` code fences - `.py` scripts in py:percent format Behavior: - Jupyter notebooks: outputs are stripped. * Markdown files: only `{python}` fenced code blocks are converted. Example: \- Python scripts: - If already a valid marimo notebook, no conversion is performed. - Otherwise, marimo attempts to convert using py:percent formatting, preserving top-level comments and docstrings. Example usage: `marimo convert your_nb.ipynb -o your_nb.py` or `marimo convert your_nb.md -o your_nb.py` or `marimo convert script.py -o your_nb.py` After conversion: Note: Since marimo's reactive execution differs from traditional notebooks, you may need to refactor code that mutates variables across cells (e.g., modifying a dataframe in multiple cells), which can lead to unexpected behavior. **Usage:** `[](#__codelineno-6-1)marimo convert [OPTIONS] FILENAME` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `-o`, `--output` | path | Output file to save the converted notebook to. If not provided, the converted notebook will be printed to stdout. | None | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo edit[¶](#marimo-edit "Permanent link") --------------------------------------------- Create or edit notebooks. * marimo edit Start the marimo notebook server * marimo edit notebook.py Create or edit notebook.py **Usage:** `[](#__codelineno-7-1)marimo edit [OPTIONS] [NAME] [ARGS]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `-p`, `--port` | integer | Port to attach to. | None | | `--host` | text | Host to attach to. | `127.0.0.1` | | `--proxy` | text | Address of reverse proxy. | None | | `--headless` | boolean | Don't launch a browser. | `False` | | `--token` / `--no-token` | boolean | Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used. | `True` | | `--token-password` | text | Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set. | None | | `--token-password-file` | text | Path to file containing token password, or '-' for stdin. Mutually exclusive with --token-password. | None | | `--base-url` | text | Base URL for the server. Should start with a /. | \`\` | | `--allow-origins` | text | Allowed origins for CORS. Can be repeated. Use \* for all origins. | None | | `--skip-update-check` | boolean | Don't check if a new version of marimo is available for download. | `False` | | `--sandbox` / `--no-sandbox` | boolean | Run the notebook in an isolated environment, with dependencies tracked via PEP 723 inline metadata. If already declared, dependencies will install automatically. Requires uv. | None | | `--watch` | boolean | Watch the file for changes and reload the code when saved in another editor. | `False` | | `--skew-protection` / `--no-skew-protection` | boolean | Enable skew protection middleware to prevent version mismatch issues. | `True` | | `--timeout` | float | Enable a global timeout to shut down the server after specified number of minutes of no connection | None | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo env[¶](#marimo-env "Permanent link") ------------------------------------------- Print out environment information for debugging purposes. **Usage:** **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo export[¶](#marimo-export "Permanent link") ------------------------------------------------- Export a notebook to various formats. **Usage:** `[](#__codelineno-9-1)marimo export [OPTIONS] COMMAND [ARGS]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo export html[¶](#marimo-export-html "Permanent link") Run a notebook and export it as an HTML file. Example: `marimo export html notebook.py -o notebook.html` Optionally pass CLI args to the notebook: `marimo export html notebook.py -o notebook.html -- -arg1 foo -arg2 bar` **Usage:** `[](#__codelineno-10-1)marimo export html [OPTIONS] NAME [ARGS]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--include-code` / `--no-include-code` | boolean | Include notebook code in the exported HTML file. | `True` | | `--watch` / `--no-watch` | boolean | Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s. | `False` | | `-o`, `--output` | path | Output file to save the HTML to. If not provided, the HTML will be printed to stdout. | None | | `--sandbox` / `--no-sandbox` | boolean | Run the command in an isolated virtual environment using `uv run --isolated`. Requires `uv`. | None | | `-f`, `--force` | boolean | Force overwrite of the output file if it already exists. | `False` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo export html-wasm[¶](#marimo-export-html-wasm "Permanent link") Export a notebook as a WASM-powered standalone HTML file. Example: `marimo export html-wasm notebook.py -o notebook.wasm.html` The exported HTML file will run the notebook using WebAssembly, making it completely self-contained and executable in the browser. This lets you share interactive notebooks on the web without setting up infrastructure to run Python code. The exported notebook runs using Pyodide, which supports most but not all Python packages. To learn more, see the Pyodide documentation. In order for this file to be able to run, it must be served over HTTP, and cannot be opened directly from the file system (e.g. file://). **Usage:** `[](#__codelineno-11-1)marimo export html-wasm [OPTIONS] NAME` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `-o`, `--output` | path | Output directory to save the HTML to. | `Sentinel.UNSET` | | `--mode` | choice (`edit` | `run`) | Whether the notebook code should be editable or readonly. | `run` | | `--watch` / `--no-watch` | boolean | Whether to watch the original file and export upon change | `False` | | `--show-code` / `--no-show-code` | boolean | Whether to show code by default in the exported HTML file; only relevant for run mode. | `False` | | `--include-cloudflare` / `--no-include-cloudflare` | boolean | Whether to include Cloudflare Worker configuration files (index.js and wrangler.jsonc) for easy deployment. | `False` | | `--sandbox` / `--no-sandbox` | boolean | Run the command in an isolated virtual environment using `uv run --isolated`. Requires `uv`. | None | | `-f`, `--force` | boolean | Force overwrite of the output file if it already exists. | `False` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo export ipynb[¶](#marimo-export-ipynb "Permanent link") Export a marimo notebook as a Jupyter notebook in topological order. Example: `marimo export ipynb notebook.py -o notebook.ipynb` Watch for changes and regenerate the script on modification: `marimo export ipynb notebook.py -o notebook.ipynb --watch` Requires nbformat to be installed. **Usage:** `[](#__codelineno-12-1)marimo export ipynb [OPTIONS] NAME` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--sort` | choice (`top-down` | `topological`) | Sort cells top-down or in topological order. | `topological` | | `--watch` / `--no-watch` | boolean | Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s. | `False` | | `-o`, `--output` | path | Output file to save the ipynb file to. If not provided, the ipynb contents will be printed to stdout. | None | | `--include-outputs` / `--no-include-outputs` | boolean | Run the notebook and include outputs in the exported ipynb file. | `False` | | `--sandbox` / `--no-sandbox` | boolean | Run the command in an isolated virtual environment using `uv run --isolated`. Requires `uv`. | None | | `-f`, `--force` | boolean | Force overwrite of the output file if it already exists. | `False` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo export md[¶](#marimo-export-md "Permanent link") Export a marimo notebook as a code fenced Markdown file. Example: `marimo export md notebook.py -o notebook.md` Watch for changes and regenerate the script on modification: `marimo export md notebook.py -o notebook.md --watch` **Usage:** `[](#__codelineno-13-1)marimo export md [OPTIONS] NAME` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--watch` / `--no-watch` | boolean | Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s. | `False` | | `-o`, `--output` | path | Output file to save the markdown to. If not provided, markdown will be printed to stdout. | None | | `--sandbox` / `--no-sandbox` | boolean | Run the command in an isolated virtual environment using `uv run --isolated`. Requires `uv`. | None | | `-f`, `--force` | boolean | Force overwrite of the output file if it already exists. | `False` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | ### marimo export script[¶](#marimo-export-script "Permanent link") Export a marimo notebook as a flat script, in topological order. Example: `marimo export script notebook.py -o notebook.script.py` Watch for changes and regenerate the script on modification: `marimo export script notebook.py -o notebook.script.py --watch` **Usage:** `[](#__codelineno-14-1)marimo export script [OPTIONS] NAME` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--watch` / `--no-watch` | boolean | Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s. | `False` | | `-o`, `--output` | path | Output file to save the script to. If not provided, the script will be printed to stdout. | None | | `--sandbox` / `--no-sandbox` | boolean | Run the command in an isolated virtual environment using `uv run --isolated`. Requires `uv`. | None | | `-f`, `--force` | boolean | Force overwrite of the output file if it already exists. | `False` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo new[¶](#marimo-new "Permanent link") ------------------------------------------- Create an empty notebook, or generate from a prompt with AI * marimo new Create an empty notebook * marimo new "Plot an interactive 3D surface with matplotlib." Generate a notebook from a prompt. * marimo new prompt.txt Generate a notebook from a file containing a prompt. Visit [https://marimo.app/ai](https://marimo.app/ai) for more prompt examples. **Usage:** `[](#__codelineno-15-1)marimo new [OPTIONS] [PROMPT]` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `-p`, `--port` | integer | Port to attach to. | None | | `--host` | text | Host to attach to. | `127.0.0.1` | | `--proxy` | text | Address of reverse proxy. | None | | `--headless` | boolean | Don't launch a browser. | `False` | | `--token` / `--no-token` | boolean | Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used. | `True` | | `--token-password` | text | Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set. | None | | `--token-password-file` | text | Path to file containing token password, or '-' for stdin. Mutually exclusive with --token-password. | None | | `--base-url` | text | Base URL for the server. Should start with a /. | \`\` | | `--sandbox` / `--no-sandbox` | boolean | Run the notebook in an isolated environment, with dependencies tracked via PEP 723 inline metadata. If already declared, dependencies will install automatically. Requires uv. | None | | `--skew-protection` / `--no-skew-protection` | boolean | Enable skew protection middleware to prevent version mismatch issues. | `True` | | `--timeout` | float | Enable a global timeout to shut down the server after specified number of minutes of no connection | None | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo recover[¶](#marimo-recover "Permanent link") --------------------------------------------------- Recover a marimo notebook from JSON. **Usage:** `[](#__codelineno-16-1)marimo recover [OPTIONS] NAME` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo run[¶](#marimo-run "Permanent link") ------------------------------------------- Run a notebook as an app in read-only mode. If NAME is a url, the notebook will be downloaded to a temporary file. Example: **Usage:** `[](#__codelineno-17-1)marimo run [OPTIONS] NAME [ARGS]...` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `-p`, `--port` | integer | Port to attach to. | None | | `--host` | text | Host to attach to. | `127.0.0.1` | | `--proxy` | text | Address of reverse proxy. | None | | `--headless` | boolean | Don't launch a browser. | `False` | | `--token` / `--no-token` | boolean | Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used. | `False` | | `--token-password` | text | Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set. | None | | `--token-password-file` | text | Path to file containing token password, or '-' for stdin. Mutually exclusive with --token-password. | None | | `--include-code` | boolean | Include notebook code in the app. | `False` | | `--session-ttl` | integer | Seconds to wait before closing a session on websocket disconnect. | `120` | | `--watch` | boolean | Watch the file for changes and reload the app. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s. | `False` | | `--skew-protection` / `--no-skew-protection` | boolean | Enable skew protection middleware to prevent version mismatch issues. | `True` | | `--base-url` | text | Base URL for the server. Should start with a /. | \`\` | | `--allow-origins` | text | Allowed origins for CORS. Can be repeated. | None | | `--redirect-console-to-browser` | boolean | Redirect console logs to the browser console. | `False` | | `--sandbox` / `--no-sandbox` | boolean | Run the notebook in an isolated environment, with dependencies tracked via PEP 723 inline metadata. If already declared, dependencies will install automatically. Requires uv. | None | | `--check` / `--no-check` | boolean | Disable a static check of the notebook before running. | `True` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo shell-completion[¶](#marimo-shell-completion "Permanent link") --------------------------------------------------------------------- Install shell completions for marimo. Supports bash, zsh, and fish. **Usage:** `[](#__codelineno-18-1)marimo shell-completion [OPTIONS]` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `--help`, `-h` | boolean | Show this message and exit. | `False` | marimo tutorial[¶](#marimo-tutorial "Permanent link") ----------------------------------------------------- Open a tutorial. marimo is a powerful library for making reactive notebooks and apps. To get the most out of marimo, get started with a few tutorials, starting with the intro: Recommended sequence: `- intro - dataflow - ui - markdown - plots - sql - layout - fileformat - markdown-format - for-jupyter-users` **Usage:** `[](#__codelineno-19-1)marimo tutorial [OPTIONS] {intro|dataflow|ui|markdown|plots|sql|layout|filefor [](#__codelineno-19-2) mat|markdown-format|for-jupyter-users}` **Options:** | Name | Type | Description | Default | | --- | --- | --- | --- | | `-p`, `--port` | integer | Port to attach to. | None | | `--host` | text | Host to attach to. | `127.0.0.1` | | `--proxy` | text | Address of reverse proxy. | None | | `--headless` | boolean | Don't launch a browser. | `False` | | `--token` / `--no-token` | boolean | Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used. | `True` | | `--token-password` | text | Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set. | None | | `--token-password-file` | text | Path to file containing token password, or '-' for stdin. Mutually exclusive with --token-password. | None | | `--skew-protection` / `--no-skew-protection` | boolean | Enable skew protection middleware to prevent version mismatch issues. | `True` | | `--help`, `-h` | boolean | Show this message and exit. | `False` | FAQ - marimo https://docs.marimo.io/faq/ Choosing marimo[¶](#choosing-marimo "Permanent link") ----------------------------------------------------- ### How is marimo different from Jupyter?[¶](#how-is-marimo-different-from-jupyter "Permanent link") marimo is a reinvention of the Python notebook as a reproducible, interactive, and shareable Python program that can be executed as scripts or deployed as interactive web apps. **Consistent state.** In marimo, your notebook code, outputs, and program state are guaranteed to be consistent. Run a cell and marimo reacts by automatically running the cells that reference its variables. Delete a cell and marimo scrubs its variables from program memory, eliminating hidden state. **Built-in interactivity.** marimo also comes with [UI elements](https://docs.marimo.io/guides/interactivity/) like sliders, a dataframe transformer, and interactive plots that are automatically synchronized with Python. Interact with an element and the cells that use it are automatically re-run with its latest value. **Pure Python programs.** Unlike Jupyter notebooks, marimo notebooks are stored as pure Python files that can be executed as scripts, deployed as interactive web apps, and versioned easily with Git. ### What problems does marimo solve?[¶](#what-problems-does-marimo-solve "Permanent link") marimo solves problems in reproducibility, maintainability, interactivity, reusability, and shareability of notebooks. **Reproducibility.** In Jupyter notebooks, the code you see doesn't necessarily match the outputs on the page or the program state. If you delete a cell, its variables stay in memory, which other cells may still reference; users can execute cells in arbitrary order. This leads to widespread reproducibility issues. [One study](https://blog.jetbrains.com/datalore/2020/12/17/we-downloaded-10-000-000-jupyter-notebooks-from-github-this-is-what-we-learned/#consistency-of-notebooks) analyzed 10 million Jupyter notebooks and found that 36% of them weren't reproducible. In contrast, marimo guarantees that your code, outputs, and program state are consistent, eliminating hidden state and making your notebook reproducible. marimo achieves this by intelligently analyzing your code and understanding the relationships between cells, and automatically re-running cells as needed. In addition, marimo notebooks can serialize package requirements inline; marimo runs these "sandboxed" notebooks in temporary virtual environments, making them [reproducible down to the packages](https://docs.marimo.io/guides/editor_features/package_management/). **Maintainability.** marimo notebooks are stored as pure Python programs (`.py` files). This lets you version them with Git; in contrast, Jupyter notebooks are stored as JSON and require extra steps to version. **Interactivity.** marimo notebooks come with [UI elements](https://docs.marimo.io/guides/interactivity/) that are automatically synchronized with Python (like sliders, dropdowns); _eg_, scrub a slider and all cells that reference it are automatically re-run with the new value. This is difficult to get working in Jupyter notebooks. **Reusability.** marimo notebooks can be executed as Python scripts from the command-line (since they're stored as `.py` files). In contrast, this requires extra steps to do for Jupyter, such as copying and pasting the code out or using external frameworks. We also let you import symbols (functions, classes) defined in a marimo notebook into other Python programs/notebooks, something you can't easily do with Jupyter. **Shareability.** Every marimo notebook can double as an interactive web app, complete with UI elements, which you can serve using the `marimo run` command. This isn't possible in Jupyter without substantial extra effort. _To learn more about problems with traditional notebooks, see these references [\[1\]](https://austinhenley.com/pubs/Chattopadhyay2020CHI_NotebookPainpoints.pdf) [\[2\]](https://www.youtube.com/watch?v=7jiPeIFXb6U&t=1s)._ ### How is `marimo.ui` different from Jupyter widgets?[¶](#how-is-marimoui-different-from-jupyter-widgets "Permanent link") Unlike Jupyter widgets, marimo's interactive elements are automatically synchronized with the Python kernel: no callbacks, no observers, no manually re-running cells. Using marimo[¶](#using-marimo "Permanent link") ----------------------------------------------- ### Is marimo a notebook or a library?[¶](#is-marimo-a-notebook-or-a-library "Permanent link") marimo is both a notebook and a library. * Create _marimo notebooks_ with the editor that opens in your browser when you run `marimo edit`. * Use the _marimo library_ (`import marimo as mo`) in marimo notebooks. Write markdown with `mo.md(...)`, create stateful interactive elements with `mo.ui` (`mo.ui.slider(...)`), and more. See the docs for an [API reference](https://docs.marimo.io/api/). ### What's the difference between a marimo notebook and a marimo app?[¶](#whats-the-difference-between-a-marimo-notebook-and-a-marimo-app "Permanent link") marimo programs are notebooks, apps, or both, depending on how you use them. There are two ways to interact with a marimo program: 1. open it as a computational _notebook_ with `marimo edit` 2. run it as an interactive _app_ with `marimo run` All marimo programs start as notebooks, since they are created with `marimo edit`. Because marimo notebooks are reactive and have built-in interactive elements, many can easily be made into useful and beautiful apps by simply hiding the notebook code: this is what `marimo run` does. Not every notebook needs to be run as an app — marimo notebooks are useful in and of themselves for rapidly exploring data and doing reproducible science. And not every app is improved by interacting with the notebook. In some settings, such as collaborative research, education, and technical presentations, going back and forth between the notebook view and app view (which you can do from `marimo edit`) can be useful! ### How does marimo know what cells to run?[¶](#how-does-marimo-know-what-cells-to-run "Permanent link") marimo reads each cell once to determine what global names it defines and what global names it reads. When a cell is run, marimo runs all other cells that read any of the global names it defines. A global name can refer to a variable, class, function, or import. In other words, marimo uses _static analysis_ to make a dataflow graph out of your cells. Each cell is a node in the graph across which global variables "flow". Whenever a cell is run, either because you changed its code or interacted with a UI element it reads, all its descendants run in turn. ### Does marimo slow my code down?[¶](#does-marimo-slow-my-code-down "Permanent link") No, marimo doesn't slow your code down. marimo determines the dependencies among cells by reading your code, not running or tracing it, so there's zero runtime overhead. ### How do I prevent automatic execution from running expensive cells?[¶](#how-do-i-prevent-automatic-execution-from-running-expensive-cells "Permanent link") Reactive (automatic) execution ensures your code and outputs are always in sync, improving reproducibility by eliminating hidden state and out-of-order execution; marimo also takes care to run only the minimal set of cells needed to keep your notebook up to date. But when some cells take a long time to run, it's understandable to be concerned that automatic execution will kick off expensive cells before you're ready to run them. _Here are some tips to avoid accidental execution of expensive cells:_ * [Disable expensive cells](https://docs.marimo.io/guides/reactivity/#disabling-cells). When a cell is disabled, it and its descendants are blocked from running. * Wrap UI elements in a [form](https://docs.marimo.io/api/inputs/form/#marimo.ui.form " marimo.ui.form"). * Use [`mo.stop`](https://docs.marimo.io/api/control_flow/#marimo.stop " marimo.stop") to conditionally stop execution of a cell and its descendants. * Decorate functions with marimo's [`mo.cache`](https://docs.marimo.io/api/caching/#marimo.cache " marimo.cache") to cache expensive intermediate computations. * Use [`mo.persistent_cache`](https://docs.marimo.io/api/caching/#marimo.persistent_cache " marimo.persistent_cache") to cache variables to disk; on re-run, marimo will read values from disk instead of recalculating them as long as the cell is not stale. * Disable automatic execution in the [runtime configuration](https://docs.marimo.io/guides/configuration/runtime_configuration/). ### How do I disable automatic execution?[¶](#how-do-i-disable-automatic-execution "Permanent link") You can disable automatic execution through the notebook runtime settings; see the [guide on runtime configuration](https://docs.marimo.io/guides/configuration/runtime_configuration/). When automatic execution is disabled, marimo still gives you guarantees on your notebook state and automatically marks cells as stale when appropriate. ### How do I use sliders and other interactive elements?[¶](#how-do-i-use-sliders-and-other-interactive-elements "Permanent link") Interactive UI elements like sliders are available in `marimo.ui`. * Assign the UI element to a global variable (`slider = mo.ui.slider(0, 100)`) * Include it in the last expression of a cell to display it (`slider` or `mo.md(f"Choose a value: {slider}")`) * Read its current value in another cell via its `value` attribute (`slider.value`) _When a UI element bound to a global variable is interacted with, all cells referencing the global variable are run automatically_. If you have many UI elements or don't know the elements you'll create until runtime, use `marimo.ui.array` and `marimo.ui.dictionary` to create UI elements that wrap other UI elements (`sliders = mo.ui.array([slider(1, 100) for _ in range(n_sliders)])`). All this and more is explained in the UI tutorial. Run it with at the command line. ### How do I add a submit button to UI elements?[¶](#how-do-i-add-a-submit-button-to-ui-elements "Permanent link") Use the `form` method to add a submit button to a UI element. For example, `[](#__codelineno-1-1)form = marimo.ui.text_area().form()` When wrapped in a form, the text area's value will only be sent to Python when you click the submit button. Access the last submitted value of the text area with `form.value`. ### How do I write markdown?[¶](#how-do-i-write-markdown "Permanent link") Import `marimo` (as `mo`) in a notebook, and use the `mo.md` function. Learn more in the [outputs guide](https://docs.marimo.io/guides/outputs/#markdown) or by running `marimo tutorial markdown`. ### How do I display plots?[¶](#how-do-i-display-plots "Permanent link") Include plots in the last expression of a cell to display them, just like all other outputs. If you're using matplotlib, you can display the `Figure` object (get the current figure with `plt.gcf()`). For examples, run the plots tutorial: Also see the [plotting API reference](https://docs.marimo.io/api/plotting/). ### How do I prevent matplotlib plots from being cut off?[¶](#how-do-i-prevent-matplotlib-plots-from-being-cut-off "Permanent link") If your legend or axes labels are cut off, try calling `plt.tight_layout()` before outputting your plot: `[](#__codelineno-3-1)import matplotlib.pyplot as plt [](#__codelineno-3-2)[](#__codelineno-3-3)plt.plot([-8, 8]) [](#__codelineno-3-4)plt.ylabel("my variable") [](#__codelineno-3-5)plt.tight_layout() [](#__codelineno-3-6)plt.gca()` ### How do I display interactive matplotlib plots?[¶](#how-do-i-display-interactive-matplotlib-plots "Permanent link") Use [`marimo.mpl.interactive`](https://docs.marimo.io/api/plotting/#marimo.mpl.interactive " marimo.mpl.interactive"). `[](#__codelineno-4-1)fig, ax = plt.subplots() [](#__codelineno-4-2)ax.plot([1, 2]) [](#__codelineno-4-3)mo.mpl.interactive(ax)` ### How do I display objects in rows and columns?[¶](#how-do-i-display-objects-in-rows-and-columns "Permanent link") Use `marimo.hstack` and `marimo.vstack`. See the layout tutorial for details: ### How do I show cell code in the app view?[¶](#how-do-i-show-cell-code-in-the-app-view "Permanent link") Use [`mo.show_code`](https://docs.marimo.io/api/outputs/#marimo.show_code " marimo.show_code"). ### How do I create an output with a dynamic number of UI elements?[¶](#how-do-i-create-an-output-with-a-dynamic-number-of-ui-elements "Permanent link") Use [`mo.ui.array`](https://docs.marimo.io/api/inputs/array/#marimo.ui.array " marimo.ui.array"), [`mo.ui.dictionary`](https://docs.marimo.io/api/inputs/dictionary/#marimo.ui.dictionary " marimo.ui.dictionary"), or [`mo.ui.batch`](https://docs.marimo.io/api/inputs/batch/#marimo.ui.batch " marimo.ui.batch") to create a UI element that wraps a dynamic number of other UI elements. If you need custom formatting, use [`mo.ui.batch`](https://docs.marimo.io/api/inputs/batch/#marimo.ui.batch " marimo.ui.batch"), otherwise use [`mo.ui.array`](https://docs.marimo.io/api/inputs/array/#marimo.ui.array " marimo.ui.array") or [`mo.ui.dictionary`](https://docs.marimo.io/api/inputs/dictionary/#marimo.ui.dictionary " marimo.ui.dictionary"). For usage examples, see the [recipes for grouping UI elements together](https://docs.marimo.io/recipes/#grouping-ui-elements-together). ### How do I restart a notebook?[¶](#how-do-i-restart-a-notebook "Permanent link") To clear all program memory and restart the notebook from scratch, open the notebook menu in the top right and click "Restart kernel". ### How do I reload modules?[¶](#how-do-i-reload-modules "Permanent link") Enable automatic reloading of modules via the runtime settings in your marimo installation's user configuration. (Click the "gear" icon in the top right of a marimo notebook). When enabled, marimo will automatically hot-reload modified modules before executing a cell. ### Why aren't my `on_change`/`on_click` handlers being called?[¶](#why-arent-my-on_changeon_click-handlers-being-called "Permanent link") A UI Element's `on_change` (or for buttons, `on_click`) handlers are only called if the element is bound to a global variable. For example, this won't work `[](#__codelineno-6-1)mo.vstack([mo.ui.button(on_change=lambda _: print("I was called")) for _ in range(10)])` In such cases (when you want to output a dynamic number of UI elements), you need to use [`mo.ui.array`](https://docs.marimo.io/api/inputs/array/#marimo.ui.array " marimo.ui.array"), [`mo.ui.dictionary`](https://docs.marimo.io/api/inputs/dictionary/#marimo.ui.dictionary " marimo.ui.dictionary"), or [`mo.ui.batch`](https://docs.marimo.io/api/inputs/batch/#marimo.ui.batch " marimo.ui.batch"). See the [recipes for grouping UI elements together](https://docs.marimo.io/recipes/#grouping-ui-elements-together) for example code. ### Why are my `on_change` handlers in an array all referencing the last element?[¶](#why-are-my-on_change-handlers-in-an-array-all-referencing-the-last-element "Permanent link") **Don't do this**: In the below snippet, every `on_change` will print `9`!. `[](#__codelineno-7-1)array = mo.ui.array( [](#__codelineno-7-2) [mo.ui.button(on_change=lambda value: print(i)) for i in range(10) [](#__codelineno-7-3)])` **Instead, do this**: Explicitly bind `i` to the current loop value: `[](#__codelineno-8-1)array = mo.ui.array( [](#__codelineno-8-2) [mo.ui.button(on_change=lambda value, i=i: print(i)) for i in range(10)] [](#__codelineno-8-3)) [](#__codelineno-8-4)array` This is necessary because [in Python, closures are late-binding](https://docs.python-guide.org/writing/gotchas/#late-binding-closures). ### Why aren't my SQL brackets working?[¶](#why-arent-my-sql-brackets-working "Permanent link") Our "SQL" cells are really just Python under the hood to keep notebooks as pure Python scripts. By default, we use `f-strings` for SQL strings, which allows for parameterized SQL like `SELECT * from table where value < {min}`. To escape real `{` / `}` that you don't want parameterized, use double `\{\{...\}\}`: `[](#__codelineno-9-1)SELECT unnest([\{\{'a': 42, 'b': 84\}\}, \{\{'a': 100, 'b': NULL\}\}]);` ### How does marimo treat type annotations?[¶](#how-does-marimo-treat-type-annotations "Permanent link") Type annotations are registered as references of a cell, unless they are explicitly written as strings. This helps ensure correctness of code that depends on type annotations at runtime (_e.g._, Pydantic), while still providing a way to omit annotations from affecting dataflow graph. For example, in `A` is treated as a reference, used in determining the dataflow graph, but in `A` isn't made a reference. For Python 3.12+, marimo additionally implements annotation scoping. ### How do I use dotenv?[¶](#how-do-i-use-dotenv "Permanent link") The package `dotenv`'s `loadenv()` function does not work out-of-the box in marimo. Instead, use `dotenv.load_dotenv(dotenv.find_dotenv(usecwd=True))`. ### What packages can I use?[¶](#what-packages-can-i-use "Permanent link") You can use any Python package. marimo cells run arbitrary Python code. ### How do I use marimo on a remote server?[¶](#how-do-i-use-marimo-on-a-remote-server "Permanent link") Use SSH port-forwarding to run marimo on a remote server and connect to it from a browser on your local machine. Make sure to pass the `--headless` flag when starting marimo on remote; on the remote machine, we also recommend using a port other than marimo's default port, such as 8080: _On the remote machine, run:_ `[](#__codelineno-12-1)marimo edit --headless --port 8080` or, if you want to set a custom host: `[](#__codelineno-13-1)marimo edit --headless --host 0.0.0.0 --port 8080` _On local, run:_ `[](#__codelineno-14-1)ssh -N -L 3718:127.0.0.1:8080 REMOTE_USER@REMOTE_HOST` Then open `localhost:3718` in your browser. ### How do I make marimo accessible on all network interfaces?[¶](#how-do-i-make-marimo-accessible-on-all-network-interfaces "Permanent link") Use `--host 0.0.0.0` with `marimo edit`, `marimo run`, or `marimo tutorial`: `[](#__codelineno-15-1)marimo edit --host 0.0.0.0` ### How do I use marimo behind JupyterHub?[¶](#how-do-i-use-marimo-behind-jupyterhub "Permanent link") JupyterHub can be configured to launch marimo using the [`jupyter-marimo-proxy` package](https://github.com/jyio/jupyter-marimo-proxy). ### How do I use marimo with JupyterBook?[¶](#how-do-i-use-marimo-with-jupyterbook "Permanent link") [JupyterBook](https://jupyterbook.org/en/stable/intro.html) makes it easy to create static websites with markdown and Jupyter notebooks. To include a marimo notebook in a JupyterBook, you can either export your notebook to an `ipynb` file, or export to `HTML`: 1. export to ipynb: `marimo export ipynb my_notebook.py -o my_notebook.ipynb --include-outputs` 2. export to HTML: `marimo export html my_notebook.py -o my_notebook.html` ### How do I deploy apps?[¶](#how-do-i-deploy-apps "Permanent link") Use the marimo CLI's `run` command to serve a notebook as an app: If you are running marimo inside a Docker container, you may want to run under a different host and port: `[](#__codelineno-17-1)marimo run notebook.py --host 0.0.0.0 --port 8080` ### Is marimo free?[¶](#is-marimo-free "Permanent link") Yes! Community - marimo https://docs.marimo.io/community/ We're building a community. Come hang out with us! * 🌟 [Star us on GitHub](https://github.com/marimo-team/marimo) * 💬 [Chat with us on Discord](https://marimo.io/discord?ref=readme) * 📧 [Subscribe to our Newsletter](https://marimo.io/newsletter) * ☁️ [Join our Cloud Waitlist](https://marimo.io/cloud) * ✏️ [Start a GitHub Discussion](https://github.com/marimo-team/marimo/discussions) * 🦋 [Follow us on Bluesky](https://bsky.app/profile/marimo.io) * 🐦 [Follow us on Twitter](https://twitter.com/marimo_io) * 🎥 [Subscribe on YouTube](https://www.youtube.com/@marimo-team) * 🕴️ [Follow us on LinkedIn](https://www.linkedin.com/company/marimo-io) Shields[¶](#shields "Permanent link") ------------------------------------- You can use our shield for opening a marimo application: * * * **Markdown** `[](#__codelineno-0-1)[![marimo](https://marimo.io/shield.svg)](https://marimo.app/l/c7h6pz)` **HTML** `[](#__codelineno-1-1) [](#__codelineno-1-2) [](#__codelineno-1-3)` Integrations - marimo https://docs.marimo.io/integrations/ It is easy to integrate your preferred data sources or data warehouses with marimo. Since marimo is strictly Python, you can utilize any Python library to access your data. In this section, we provide some examples of how to integrate with popular data sources. | Integration | Description | | --- | --- | | [MotherDuck](https://docs.marimo.io/integrations/motherduck/) | Integrating with MotherDuck | | [Google Cloud Storage](https://docs.marimo.io/integrations/google_cloud_storage/) | Integrating with Google Cloud Storage | | [Google Cloud BigQuery](https://docs.marimo.io/integrations/google_cloud_bigquery/) | Integrating with Google Cloud BigQuery | | [Google Sheets](https://docs.marimo.io/integrations/google_sheets/) | Integrating with Google Sheets | Security - marimo https://docs.marimo.io/security/ marimo takes security seriously. This document describes marimo's security model, our approach to vulnerability disclosure, and how to report security issues. Security Model[¶](#security-model "Permanent link") --------------------------------------------------- When you open a notebook, marimo assumes you might not trust its contents until you explicitly choose to run it. Once you've run code, marimo treats the outputs as trusted since they came from your execution. Like other notebooks, marimo allows arbitrary code execution when you run cells. This means that if you run code from untrusted sources, you could inadvertently execute malicious code. Therefore, it's important to only run notebooks from sources you trust or to review the code before executing it. However, marimo implements several security measures to minimize risks when opening and editing notebooks. Our blanket policy is that no user code is executed without explicit user action (either as javascript or python). ### Content sanitization[¶](#content-sanitization "Permanent link") marimo sanitizes HTML and JavaScript in specific contexts to prevent malicious code from executing when you open untrusted notebooks. All user content shown before execution is sanitized to remove all scripts (including markdown and custom HTML outputs). After initial execution, outputs are trusted since they were generated by your code. Being a responsible notebook user means running code from sources you trust, and/or reviewing code before executing it. ### Static loading[¶](#static-loading "Permanent link") Although marimo notebook are just python files, opening a notebook through `marimo edit` does not execute it as a module. marimo notebooks are statically loaded, meaning they are parsed but not executed as Python modules when opened. This prevents arbitrary code execution at load time. Code only runs when you explicitly execute cells. ### Run modes and trust[¶](#run-modes-and-trust "Permanent link") marimo behaves differently depending on how you run it: **Edit mode** (`marimo edit`): - Content is sanitized until you run your first cell - After you run code, subsequent outputs are trusted (you created them) - Token authentication enabled by default for remote access **Run mode** (`marimo run`): - Notebooks run as web applications - Content is treated as a trusted website (no sanitization) - Token authentication can be configured via CLI flags or custom middleware This distinction reflects the different threat models: editing is exploratory and may involve untrusted notebooks; deployed apps are intentional publications. ### Authentication[¶](#authentication "Permanent link") marimo provides token-based authentication: * Enabled by default when running `marimo edit` * Configurable in run mode via `--token` and `--token-password` flags * Extensible through ASGI middleware for custom authentication schemes See the [Authentication guide](https://docs.marimo.io/guides/deploying/authentication/) for more details. ### Added security measures on [https://molab.marimo.io](https://molab.marimo.io/)[¶](#added-security-measures-on-httpsmolabmarimoio "Permanent link") [molab](https://molab.marimo.io/) takes a few other addition precautions. * Auto-running cells is disabled on notebook load (you can disable this during your session) * Custom head tags are disabled These restrictions prevent code execution without explicit user consent. Security Advisories[¶](#security-advisories "Permanent link") ------------------------------------------------------------- marimo publishes security advisories for vulnerabilities that affect production deployments, particularly long-running applications. We follow responsible disclosure practices and work with security researchers to address issues. ### CVE Policy[¶](#cve-policy "Permanent link") We issue CVEs and security advisories when: * A vulnerability could affect long-running app deployments * End-users are directly impacted * The issue has security implications beyond normal bug fixes For general safety improvements and hardening work, we document changes in our [release notes](https://github.com/marimo-team/marimo/releases) without issuing formal advisories. molab Security[¶](#molab-security "Permanent link") --------------------------------------------------- [molab](https://docs.marimo.io/guides/molab/) is marimo's hosted notebook platform. For security issues affecting molab: * We handle disclosure on a case-by-case basis * General security improvements are disclosed publicly when applicable, and will be documented on this page. * User-specific issues are handled privately through direct notification * Reports can be submitted through the same channels: [GitHub advisories](https://github.com/marimo-team/marimo/security/advisories/new) or security \[at\] marimo \[dot\] io Reporting Vulnerabilities[¶](#reporting-vulnerabilities "Permanent link") ------------------------------------------------------------------------- We appreciate the security research community's efforts to improve marimo's security. If you discover a vulnerability: **How to report:** 1. [Draft a security advisory on GitHub](https://github.com/marimo-team/marimo/security/advisories/new), or 2. Email the marimo team at security \[at\] marimo \[dot\] io **What to expect:** * We review all reports and respond to actionable issues * Advisories affecting end-users are escalated to CVEs when appropriate * We provide attribution for all reports (unless you prefer to remain anonymous) * We have a small allocation for bug bounties; please inquire if interested. **Recognition:** We're grateful to [the security researchers](https://github.com/marimo-team/marimo/blob/main/SECURITY.md) who have responsibly disclosed vulnerabilities. Your contributions help keep marimo safe for the entire community. We encourage responsible disclosure and recognize all security researchers who help improve marimo. Staying Up to Date[¶](#staying-up-to-date "Permanent link") ----------------------------------------------------------- marimo ships new releases approximately once per week, and we provide immediate updates for major security disclosures. To ensure you have the latest security fixes, we recommend using `uv` to keep marimo up to date: `[](#__codelineno-0-1)# Install or update to the latest version [](#__codelineno-0-2)uv pip install --upgrade marimo` Using `uv` ensures you benefit from the latest security improvements and patches as soon as they're available. Questions?[¶](#questions "Permanent link") ------------------------------------------ For security questions or concerns, please reach out to security \[at\] marimo \[dot\] io. For general questions about marimo, see our [FAQ](https://docs.marimo.io/faq/) or join us on [Discord](https://marimo.io/discord). ### Previous Advisories[¶](#previous-advisories "Permanent link") Click to expand previous security advisories * **[\[GHSA-xjv7-6w92-42r7\]](https://github.com/marimo-team/marimo/security/advisories/GHSA-xjv7-6w92-42r7)**: Unauthenticated proxy vulnerability in matplotlib endpoint. The `/mpl/[port]/[route]` endpoint allowed external attackers to reach internal services. Affected versions 0.9.20 through 0.16.3. Fixed in 0.16.4. * **\[molab-0\]**: iframe sandbox escape via markdown render. In molab, an attacker could exploit a vulnerability in the iframe sandboxing to escape the iframe and execute code in the parent context. Fixed in molab deployment on 2025-10-19. Readings & Videos - marimo https://docs.marimo.io/reading/ Resources[¶](#resources "Permanent link") ----------------------------------------- marimo is a **reinvention** of the Python notebook. As a reinvention, marimo may push to you **rethink** what a notebook **is**. The following readings and videos might help you do just that. To dive deep into what we're building and why, check out these readings: * [Our HackerNews launch, the second most upvoted Python ShowHN of all time](https://news.ycombinator.com/item?id=38971966) * [Our r/machinelearning launch](https://www.reddit.com/r/MachineLearning/comments/191rdwq/p_i_built_marimo_an_opensource_reactive_python/) * [Lessons Learned Reinventing the Python Notebook](https://marimo.io/blog/lessons-learned) * [Why Stanford Scientists Needed a New Notebook](https://marimo.io/blog/slac-marimo) * [Reinventing Python Notebooks as Reusable Python Programs](https://marimo.io/blog/python-not-json) * [Representing Python Notebooks as Dataflow Graphs](https://marimo.io/blog/dataflow) * [Nature: a Notebook for Reproducible Code](https://www.nature.com/articles/d41586-025-01241-6) See [our blog](https://marimo.io/blog) for more. YouTube[¶](#youtube "Permanent link") ------------------------------------- Our [YouTube channel](https://www.youtube.com/@marimo-team) shows you the ins and outs of using marimo for many applications, including AI, ML, data engineering, and more. You can also get started with the [marimo concepts](https://www.youtube.com/watch?v=3N6lInzq5MI&list=PLNJXGo8e1XT9jP7gPbRdm1XwloZVFvLEq) playlist, which tours many of our features. Installation - marimo https://docs.marimo.io/getting_started/installation/ Before installing marimo, we recommend creating and activating a Python [virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments). Setting up a virtual environment Python uses virtual environments to minimize conflicts among packages. Here's a quickstart for `pip` users. If you use `conda`, please use a [`conda` environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands) instead. Run the following in the terminal: * create an environment with `python -m venv marimo-env` * activate the environment: * macOS/Unix: `source marimo-env/bin/activate` * Windows: `marimo-env\Scripts\activate` _Make sure the environment is activated before installing marimo and when using marimo._ Install other packages you may need, such as numpy, pandas, matplotlib, and altair, in this environment. When you're done, deactivate the environment with `deactivate` in the terminal. Learn more from the [official Python tutorial](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments). Using uv? [uv](https://docs.astral.sh/uv/) is a next-generation Python package installer and manager that is 10-100x faster than pip, and also makes it easy to install Python and manage projects. Create a [uv project](https://docs.astral.sh/uv/guides/projects/) with `uv init`; this creates and manages a virtual environment for you behind-the-scenes. For detailed information on using marimo with `uv`, see our [uv guide](https://docs.marimo.io/guides/package_management/using_uv/). Install with minimal dependencies[¶](#install-with-minimal-dependencies "Permanent link") ----------------------------------------------------------------------------------------- To install marimo, run the following in a terminal: install with pipinstall with uvinstall with conda To check if the install worked, run To check if the install worked, run `[](#__codelineno-3-1)uv run marimo tutorial intro` `[](#__codelineno-4-1)conda install -c conda-forge marimo` To check if the install worked, run A tutorial notebook should open in your browser. Install with recommended dependencies[¶](#install-with-recommended-dependencies "Permanent link") ------------------------------------------------------------------------------------------------- marimo is lightweight, with few dependencies, to maximize compatibility with your own environments. To unlock additional features in the marimo editor, including SQL cells, AI completion, server-side plotting of dataframe columns, and more, we suggest installing `marimo[recommended]`: install with pipinstall with uvinstall with conda `[](#__codelineno-6-1)pip install "marimo[recommended]"` `[](#__codelineno-7-1)uv add "marimo[recommended]"` `[](#__codelineno-8-1)conda install -c conda-forge marimo "duckdb>=1.0.0" "altair>=5.4.0" pyarrow "polars>=1.9.0" "sqlglot[rs]>=23.4" "openai>=1.55.3" "ruff" "nbformat>=5.7.0" "vegafusion>=2.0.0" "vl-convert-python>=1.0.0"` Installing marimo in this way installs the following additional dependencies and unlocks the following features: | Dependency | Feature | | --- | --- | | duckdb>=1.0.0 | SQL cells | | altair>=5.4.0 | Plotting in datasource viewer | | polars\[pyarrow\]>=1.9.0 | SQL output back in Python | | sqlglot\[rs\]>=23.4 | SQL cells parsing | | openai>=1.55.3 | AI features | | ruff | Formatting | | nbformat>=5.7.0 | Export as IPYNB | | vegafusion>=2.0.0 | Performant charting | | vl-convert-python>=1.0.0 | Required by vegafusion | Key Concepts - marimo https://docs.marimo.io/getting_started/key_concepts/ This page covers marimo's key concepts: * marimo lets you rapidly experiment with data using Python, SQL, and interactive elements in a reproducible **notebook environment**. * Unlike Jupyter notebooks, marimo notebooks are reusable software artifacts. marimo notebooks can be shared as as **interactive web apps** and executed as **Python scripts**. Editing notebooks[¶](#editing-notebooks "Permanent link") --------------------------------------------------------- marimo notebooks are **reactive**: they automatically react to your code changes and UI interactions and keep your notebook up-to-date, not unlike a spreadsheet. This makes your notebooks reproducible, [eliminating hidden state](https://docs.marimo.io/faq/#faq-problems); it's also what enables marimo notebooks to double as apps and Python scripts. Working with expensive notebooks If you don't want cells to run automatically, the [runtime can be configured](https://docs.marimo.io/guides/configuration/runtime_configuration/) to be lazy, only running cells when you ask for them to be run and marking affected cells as stale. **See our guide on working with [expensive notebooks](https://docs.marimo.io/guides/expensive_notebooks/) for more tips.** **Create your first notebook.** After [installing marimo](https://docs.marimo.io/getting_started/installation/), create your first notebook with `[](#__codelineno-0-1)marimo edit my_notebook.py` at the command-line. **The marimo library**. We recommend starting each marimo notebook with a cell containing a single line of code, The marimo library lets you use interactive UI elements, layout elements, dynamic markdown, and more in your marimo notebooks. ### How marimo executes cells[¶](#how-marimo-executes-cells "Permanent link") A marimo notebook is made of small blocks of Python code called **cells**. _When you run a cell, marimo automatically runs all cells that read any global variables defined by that cell._ This is reactive execution. **Execution order.** The order of cells on the page has no bearing on the order cells are executed in: execution order is determined by the variables cells define and the variables they read. You have full freedom over how to organize your code and tell your stories: move helper functions and other "appendices" to the bottom of your notebook, or put cells with important outputs at the top. **No hidden state.** marimo notebooks have no hidden state because the program state is automatically synchronized with your code changes and UI interactions. And if you delete a cell, marimo automatically deletes that cell's variables, preventing painful bugs that arise in traditional notebooks. **No magical syntax.** There's no magical syntax or API required to opt-in to reactivity: cells are Python and _only Python_. Behind-the-scenes, marimo statically analyzes each cell's code just once, creating a directed acyclic graph based on the global names each cell defines and reads. This is how data flows in a marimo notebook. Minimize variable mutation. marimo's understanding of your code is based on variable definitions and references; marimo does not track mutations to objects at runtime. For this reason, 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. Learn more in our [reactivity guide](https://docs.marimo.io/guides/reactivity/#reactivity-mutations). For more on reactive execution, open the dataflow tutorial or read the [reactivity guide](https://docs.marimo.io/guides/reactivity/). To visualize and understand how data flows through your notebook, check out our [dataflow tools](https://docs.marimo.io/guides/editor_features/dataflow/). ### Visualizing outputs[¶](#visualizing-outputs "Permanent link") marimo visualizes the last expression of each cell as its **output**. Outputs can be any Python value, including markdown and interactive elements created with the marimo library, (_e.g._, [`mo.md`](https://docs.marimo.io/api/markdown/#marimo.md " marimo.md"), [`mo.ui.slider`](https://docs.marimo.io/api/inputs/slider/#marimo.ui.slider " marimo.ui.slider")). You can even interpolate Python values into markdown (using `mo.md(f"...")`) and other marimo elements to build rich composite outputs: > Thanks to reactive execution, running a cell refreshes all the relevant outputs in your notebook. The marimo library also comes with elements for laying out outputs, including [`mo.hstack`](https://docs.marimo.io/api/layouts/stacks/#marimo.hstack " marimo.hstack"), [`mo.vstack`](https://docs.marimo.io/api/layouts/stacks/#marimo.vstack " marimo.vstack"), [`mo.accordion`](https://docs.marimo.io/api/layouts/accordion/#marimo.accordion " marimo.accordion"), [`mo.ui.tabs`](https://docs.marimo.io/api/inputs/tabs/#marimo.ui.tabs " marimo.ui.tabs"), [`mo.sidebar`](https://docs.marimo.io/api/layouts/sidebar/#marimo.sidebar " marimo.sidebar"), [`mo.nav_menu`](https://docs.marimo.io/api/inputs/nav_menu/#marimo.nav_menu " marimo.nav_menu"), [`mo.ui.table`](https://docs.marimo.io/api/inputs/table/#marimo.ui.table " marimo.ui.table"), and [many more](https://docs.marimo.io/api/layouts/). For more on outputs, try these tutorials: `[](#__codelineno-3-1)marimo tutorial markdown [](#__codelineno-3-2)marimo tutorial plots [](#__codelineno-3-3)marimo tutorial layout` or read the [visualizing outputs guide](https://docs.marimo.io/guides/outputs/). ### Creating interactive elements[¶](#creating-interactive-elements "Permanent link") The marimo library comes with many interactive stateful elements in [`marimo.ui`](https://docs.marimo.io/api/inputs/), including simple ones like sliders, dropdowns, text fields, and file upload areas, as well as composite ones like forms, arrays, and dictionaries that can wrap other UI elements. **Using UI elements.** To use a UI element, create it with `mo.ui` and **assign it to a global variable.** When you interact with a UI element in your browser (_e.g._, sliding a slider), _marimo sends the new value back to Python and reactively runs all cells that use the element_, which you can access via its `value` attribute. > **This combination of interactivity and reactivity is very powerful**: use it to make your data tangible during exploration and to build all kinds of tools and apps. _marimo can only synchronize UI elements that are assigned to global variables._ Use composite elements like [`mo.ui.array`](https://docs.marimo.io/api/inputs/array/#marimo.ui.array " marimo.ui.array") and [`mo.ui.dictionary`](https://docs.marimo.io/api/inputs/dictionary/#marimo.ui.dictionary " marimo.ui.dictionary") if the set of UI elements is not known until runtime. Using buttons to execute cells Use [`mo.ui.run_button`](https://docs.marimo.io/api/inputs/run_button/#marimo.ui.run_button " marimo.ui.run_button") to create a button that triggers computation when clicked; see our recipes for [an example](https://docs.marimo.io/recipes/#create-a-button-that-triggers-computation-when-clicked). For more on interactive elements, run the UI tutorial or read the [interactivity guide](https://docs.marimo.io/guides/interactivity/). ### Querying dataframes and databases with SQL[¶](#querying-dataframes-and-databases-with-sql "Permanent link") marimo has built-in support for SQL: you can query Python dataframes, databases, CSVs, Google Sheets, or anything else. After executing your query, marimo returns the result to you as a dataframe, making it seamless to go back and forth between SQL and Python. Query a dataframe using SQL! To create a SQL cell, click on the SQL button that appears at the bottom of the cell array, or right click the create cell button next to a cell. Today, SQL in marimo is executed using [duckdb](https://duckdb.org/docs/). To learn more, run the SQL tutorial or read the [SQL guide](https://docs.marimo.io/guides/working_with_data/sql/). Running notebooks as applications[¶](#running-notebooks-as-applications "Permanent link") ----------------------------------------------------------------------------------------- You can use marimo as a notebook, similar to how you might use Jupyter. But you can also do more: because marimo notebooks are reactive and can include interactive elements, hiding notebook code gives you a simple web app! You can run your notebook as a read-only web app from the command-line: `[](#__codelineno-6-1)marimo run my_notebook.py` The default renderer just hides the notebook code and concatenates outputs vertically. But marimo also supports [other layouts](https://docs.marimo.io/guides/apps/), such as slides and grid. Running notebooks as scripts[¶](#running-notebooks-as-scripts "Permanent link") ------------------------------------------------------------------------------- Because marimo notebooks are stored as pure Python files, each notebook can be executed as a script from the command-line: You can also [pass command-line arguments](https://docs.marimo.io/guides/scripts/) to scripts. Quickstart - marimo https://docs.marimo.io/getting_started/quickstart/ Installing marimo gets you the `marimo` command-line interface (CLI), the entry point to all things marimo. Run tutorials[¶](#run-tutorials "Permanent link") ------------------------------------------------- `marimo tutorial intro` opens the intro tutorial. List all tutorials with Edit notebooks[¶](#edit-notebooks "Permanent link") --------------------------------------------------- Create and edit notebooks with `marimo edit`. * launch the notebook server to create new notebooks, and start or stop existing ones: * create or edit a single notebook with `[](#__codelineno-2-1)marimo edit your_notebook.py` (If `your_notebook.py` doesn't exist, marimo will create a blank notebook named `your_notebook.py`.) Deploy as apps[¶](#deploy-as-apps "Permanent link") --------------------------------------------------- Use `marimo run` to [serve your notebook as an app](https://docs.marimo.io/guides/apps/), with Python code hidden and uneditable. `[](#__codelineno-3-1)marimo run your_notebook.py` Run as scripts[¶](#run-as-scripts "Permanent link") --------------------------------------------------- Run your notebook as a script with You can also [pass CLI args](https://docs.marimo.io/guides/scripts/) to your notebook. Convert Jupyter notebooks and Python scripts to marimo[¶](#convert-jupyter-notebooks-and-python-scripts-to-marimo "Permanent link") ----------------------------------------------------------------------------------------------------------------------------------- Automatically convert Jupyter notebooks and Python scripts to marimo notebooks with `marimo convert`: `[](#__codelineno-5-1)# From Jupyter notebook [](#__codelineno-5-2)marimo convert your_notebook.ipynb -o your_notebook.py [](#__codelineno-5-3)[](#__codelineno-5-4)# From Python script or jupytext py:percent format [](#__codelineno-5-5)marimo convert your_script.py -o your_notebook.py` Then open the notebook with `marimo edit your_notebook.py` Disable autorun on startup marimo automatically runs notebooks when they are opened. If this is a problem for you (not all Jupyter notebooks are designed to be run on startup), you can disable autorun on startup via [user configuration](https://docs.marimo.io/guides/configuration/runtime_configuration/). 1. Type `marimo config show` to get the location of your config file. 2. If no config file exists, create it at `$XDG_CONFIG_HOME/marimo/marimo.toml`. 3. Update your config to include the following: marimo.toml `[](#__codelineno-6-1)[runtime] [](#__codelineno-6-2)auto_instantiate = false` Export marimo notebooks to other file formats[¶](#export-marimo-notebooks-to-other-file-formats "Permanent link") ----------------------------------------------------------------------------------------------------------------- Use to [export marimo notebooks](https://docs.marimo.io/guides/exporting/) to other file formats, including HTML, IPYNB, and markdown. Install optional dependencies for more features[¶](#install-optional-dependencies-for-more-features "Permanent link") --------------------------------------------------------------------------------------------------------------------- Some features require additional dependencies, which are not installed by default. This includes: * [SQL cells](https://docs.marimo.io/guides/working_with_data/sql/) * Charts in the datasource viewer * [AI features](https://docs.marimo.io/guides/editor_features/ai_completion/) * Format on save To install the optional dependencies, run: install with pipinstall with uvinstall with conda `[](#__codelineno-8-1)pip install "marimo[recommended]"` `[](#__codelineno-9-1)uv add "marimo[recommended]"` `[](#__codelineno-10-1)conda install -c conda-forge marimo duckdb altair polars openai ruff` This will install: `duckdb`, `altair`, `polars`, `openai`, and `ruff`. Enable GitHub Copilot and AI Assistant[¶](#enable-github-copilot-and-ai-assistant "Permanent link") --------------------------------------------------------------------------------------------------- The marimo editor natively supports [GitHub Copilot](https://copilot.github.com/), an AI pair programmer, similar to VS Code. _Get started with Copilot_: 1. Install [Node.js](https://nodejs.org/en/download). 2. Enable Copilot via the settings menu in the marimo editor. _Note_: Copilot is not yet available in our conda distribution; please install marimo from `PyPI` if you need Copilot. marimo also comes with support for [other copilots](https://docs.marimo.io/guides/editor_features/ai_completion/#custom-copilots), and a built-in [AI assistant](https://docs.marimo.io/guides/editor_features/ai_completion/) that helps you write code. Use [molab](https://molab.marimo.io/notebooks), a cloud-based marimo notebook service similar to Google Colab, to create and share notebook links ([docs](https://docs.marimo.io/guides/molab/)). Coming from VS Code?[¶](#coming-from-vs-code "Permanent link") -------------------------------------------------------------- The best way to use marimo is through the CLI. While we do have a VS Code extension, we are actively rewriting it to provide a more native and robust experience, similar to what you may be used to for Jupyter notebooks. In the meantime, we recommend using the CLI. You can try our [existing extension](https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo), but please be aware that you may run into issues, and that a revamped extension is coming soon. Running cells - marimo https://docs.marimo.io/guides/reactivity/ marimo _reacts_ to your code changes: run a cell, and all other cells that refer to the variables it defines are automatically run with the latest data. This keeps your code and outputs consistent, and eliminates bugs before they happen. Why run cells reactively? marimo's "reactive" execution model makes your notebooks more reproducible by eliminating hidden state and providing a deterministic execution order. It also powers marimo's support for [interactive elements](https://docs.marimo.io/guides/interactivity/), for running as apps, and executing as scripts. How marimo runs cells is one of the biggest differences between marimo and traditional notebooks like Jupyter. Learn more at our [FAQ](https://docs.marimo.io/faq/#faq-jupyter). Working with expensive notebooks marimo provides tools for working with expensive notebooks, in which cells might take a long time to run or have side-effects. * The [runtime can be configured](https://docs.marimo.io/guides/configuration/runtime_configuration/) to be **lazy** instead of automatic, marking cells as stale instead of running them. * Use [`mo.stop`](https://docs.marimo.io/api/control_flow/#marimo.stop " marimo.stop") to conditionally stop execution at runtime. See [the expensive notebooks guide](https://docs.marimo.io/guides/expensive_notebooks/) for more tips. How marimo runs cells[¶](#how-marimo-runs-cells "Permanent link") ----------------------------------------------------------------- marimo statically analyzes each cell (i.e., without running it) to determine its * references, the global variables it reads but doesn't define; * definitions, the global variables it defines. It then forms a directed acyclic graph (DAG) on cells, with an edge from one cell to another if the latter references any of the definitions of the former. When a cell is run, its descendants are marked for execution. Runtime Rule When a cell is run, marimo automatically runs all other cells that **reference** any of the global variables it **defines**. marimo [does not track mutations](#variable-mutations-are-not-tracked) to variables, nor assignments to attributes. That means that if you assign an attribute like `foo.bar = 10`, other cells referencing `foo.bar` will _not_ be run. ### Execution order[¶](#execution-order "Permanent link") The order cells are executed in is determined by the relationships between cells and their variables, not by the order of cells on the page (similar to a spreadsheet). This lets you organize your code in whatever way makes the most sense to you. For example, you can put helper functions at the bottom of your notebook. ### Deleting a cell deletes its variables[¶](#deleting-a-cell-deletes-its-variables "Permanent link") In marimo, _deleting a cell deletes its global variables from program memory_. Cells that previously referenced these variables are automatically re-run and invalidated (or marked as stale, depending on your [runtime configuration](https://docs.marimo.io/guides/configuration/runtime_configuration/)). In this way, marimo eliminates a common cause of bugs in traditional notebooks like Jupyter. ### Variable mutations are not tracked[¶](#variable-mutations-are-not-tracked "Permanent link") 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**. 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. Create new variables, don't mutate existing ones Mutate variables in the cells that define them Do this ...... not this `[](#__codelineno-4-1)df = pd.DataFrame({"my_column": [1, 2]}) [](#__codelineno-4-2)df["another_column"] = [3, 4]` `[](#__codelineno-5-1)df = pd.DataFrame({"my_column": [1, 2]})` `[](#__codelineno-6-1)df["another_column"] = [3, 4]` Global variable names must be unique[¶](#global-variable-names-must-be-unique "Permanent link") ----------------------------------------------------------------------------------------------- **marimo requires that every global variable be defined by only one cell.** This lets marimo keep code and outputs consistent. 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[¶](#creating-temporary-variables "Permanent link") marimo provides two ways to define temporary variables, which can help keep the number of global variables in your notebook small. #### Creating local variables[¶](#creating-local-variables "Permanent link") 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[¶](#encapsulating-code-in-functions "Permanent link") 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: `[](#__codelineno-7-1)def _(): [](#__codelineno-7-2) import matplotlib.pyplot as plt [](#__codelineno-7-3) fig, ax = plt.subplots() [](#__codelineno-7-4) ax.plot([1, 2]) [](#__codelineno-7-5) return ax [](#__codelineno-7-6)[](#__codelineno-7-7)_()` Here, the variables `plt`, `fig`, and `ax` aren't added to the globals. ### Managing memory[¶](#managing-memory "Permanent link") Because variable names must be unique, you cannot reassign variables as a means of freeing memory. Instead, manage memory by encapsulating code in functions or using the `del` operator. See our guide on [expensive notebooks](https://docs.marimo.io/guides/expensive_notebooks/#manage-memory) to learn more. Configuring how marimo runs cells[¶](#configuring-how-marimo-runs-cells "Permanent link") ----------------------------------------------------------------------------------------- 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 module autoreloader. Read our [runtime configuration guide](https://docs.marimo.io/guides/configuration/runtime_configuration/) to learn more. Disabling cells[¶](#disabling-cells "Permanent link") ----------------------------------------------------- Sometimes, you may want to edit one part of a notebook without triggering automatic execution of its dependent cells. For example, the dependent cells may take a long time to execute, and you only want to iterate on the first part of a multi-cell computation. For cases like this, marimo lets you **disable** cells: when a cell is disabled, it and its dependents are blocked from running. Disabling a cell blocks it from running. When you re-enable a cell, if any of the cell's ancestors ran while it was disabled, marimo will automatically run it. Enable a cell through the context menu. Stale cells run automatically. Interactive elements - marimo https://docs.marimo.io/guides/interactivity/ One of marimo's most powerful features is its first-class support for interactive user interface (UI) elements, or "widgets", created using [`marimo.ui`](https://docs.marimo.io/api/inputs/). **Interacting with a UI element bound to a global variable automatically runs all cells that reference it.** How interactions run cells[¶](#how-interactions-run-cells "Permanent link") --------------------------------------------------------------------------- Every UI element you make using [`marimo.ui`](https://docs.marimo.io/api/inputs/) has a value, accessible via its `value` attribute. When you interact with a UI element bound to a global variable, its value is sent back to Python. A single rule determines what happens next: Interaction rule When a UI element assigned to a global variable is interacted with, marimo automatically runs all cells that reference the variable (but don't define it). In the clip at the top of this page, interacting with the slider in the second cell re-runs the third cell (which outputs markdown) because it references the slider variable `x`. It doesn't re-run the second cell, because that cell defines `x`. **For interactions on a UI element to have any effect, the element must be assigned to a global variable.** Displaying UI elements[¶](#displaying-ui-elements "Permanent link") ------------------------------------------------------------------- Display UI elements in the output area above a cell by including them in the last expression, just like any other object. You can also embed elements in [markdown](https://docs.marimo.io/api/markdown/#marimo.md " marimo.md") using Python f-strings, like so: `[](#__codelineno-0-1)slider = mo.ui.slider(1, 10) [](#__codelineno-0-2)mo.md(f"Choose a value: {slider}")` Composite elements[¶](#composite-elements "Permanent link") ----------------------------------------------------------- Composite elements are advanced elements let you build UI elements out of other UI elements. The following composite elements are available: * [`mo.ui.array`](https://docs.marimo.io/api/inputs/array/#marimo.ui.array " marimo.ui.array") * [`mo.ui.dictionary`](https://docs.marimo.io/api/inputs/dictionary/#marimo.ui.dictionary " marimo.ui.dictionary") * [`mo.ui.batch`](https://docs.marimo.io/api/inputs/batch/#marimo.ui.batch " marimo.ui.batch") * [`mo.ui.form`](https://docs.marimo.io/api/inputs/form/#marimo.ui.form " marimo.ui.form") **Arrays and dictionaries.** Use [`mo.ui.array`](https://docs.marimo.io/api/inputs/array/#marimo.ui.array " marimo.ui.array") and [`mo.ui.dictionary`](https://docs.marimo.io/api/inputs/dictionary/#marimo.ui.dictionary " marimo.ui.dictionary") to logically group together related elements. These elements are especially useful when a set of UI elements is only known at runtime (so you can't assign each to a global variable individually, but can assign them to an array or dictionary). You can access the elements contained in an array or dictionary using Pythonic syntax, and embed these elements in other outputs. See their docstrings for code examples. **Batch and form.** Use these powerful elements to group together multiple UI elements into a single element with custom formatting, and gate the sending of an element's value on form submission. Use a form to gate value updates on submission Use an array to group together elements or create a collection of elements that is determined at runtime Building custom UI elements using our plugin API[¶](#building-custom-ui-elements-using-our-plugin-api "Permanent link") ----------------------------------------------------------------------------------------------------------------------- You can build your own reactive and interactive UI elements using [anywidget](https://github.com/manzt/anywidget). See [our docs on building custom UI elements](https://docs.marimo.io/guides/integrating_with_marimo/custom_ui_plugins/) to learn more. Visualize outputs - marimo https://docs.marimo.io/guides/outputs/ Visualizing outputs[¶](#visualizing-outputs "Permanent link") ------------------------------------------------------------- The last expression of a cell is its visual output, rendered above the cell. Outputs are included in the "app" or read-only view of the notebook. marimo comes out of the box a number of elements to help you make rich outputs, documented in the [API reference](https://docs.marimo.io/api/). Markdown[¶](#markdown "Permanent link") --------------------------------------- Markdown is written with the marimo library function [`mo.md`](https://docs.marimo.io/api/markdown/#marimo.md " marimo.md"). Writing markdown programmatically lets you make dynamic markdown: interpolate Python values into markdown strings, conditionally render your markdown, and embed markdown in other objects. Here's a simple hello world example: `[](#__codelineno-1-1)name = mo.ui.text(placeholder="Your name here") [](#__codelineno-1-2)mo.md( [](#__codelineno-1-3) f""" [](#__codelineno-1-4) Hi! What's your name? [](#__codelineno-1-5) [](#__codelineno-1-6) {name} [](#__codelineno-1-7) """ [](#__codelineno-1-8))` `[](#__codelineno-2-1)mo.md( [](#__codelineno-2-2) f""" [](#__codelineno-2-3) Hello, {name.value}! [](#__codelineno-2-4) """ [](#__codelineno-2-5))` Notice that marimo knows how to render marimo objects in markdown: you can just embed them in [`mo.md()`](https://docs.marimo.io/api/markdown/#marimo.md " marimo.md") using an f-string, and marimo will figure out how to display them! For other objects, like matplotlib plots, wrap them in [`mo.as_html()`](https://docs.marimo.io/api/html/#marimo.as_html " marimo.as_html") to tap into marimo's media viewer: `[](#__codelineno-3-1)mo.md( [](#__codelineno-3-2) f""" [](#__codelineno-3-3) Here's a plot! [](#__codelineno-3-4) [](#__codelineno-3-5) {mo.as_html(figure)} [](#__codelineno-3-6) """ [](#__codelineno-3-7))` ### Markdown editor[¶](#markdown-editor "Permanent link") marimo automatically renders cells that only use `mo.md` in a markdown editor that supports common hotkeys. You can switch between the Markdown and Python editors by clicking the button in the top right: marimo is pure Python, even when you're using markdown. **Writing LaTeX.** The markdown editor supports writing LaTeX. You should typically use a raw string for markdown with LaTeX, which you can activate by checking the `r` box in the bottom-right corner of the markdown editor. **Interpolating Python values.** Interpolating Python values requires using an `f`\-string, which you can activate by checking the `f` box in the bottom-right corner of the markdown editor. ### Markdown extensions[¶](#markdown-extensions "Permanent link") #### Details[¶](#details "Permanent link") Create expandable details with additional context: `[](#__codelineno-4-1)/// details | Heads up [](#__codelineno-4-2)[](#__codelineno-4-3)Here's some additional context. [](#__codelineno-4-4)///` Source code for `examples/markdown/details.py` Tip: paste this code into an empty cell, and the marimo editor will create cells for you ``import marimo __generated_with = "0.17.4" app = marimo.App() @app.cell(hide_code=True) def _(mo): mo.md(r""" Create expandable markdown blocks with `details`: """) return @app.cell def _(mo): mo.md(""" /// details | Hello, details! Some additional content. /// """) return @app.cell(hide_code=True) def _(mo): mo.md(r""" Style details using the "type" argument: """) return @app.cell def _(mo): mo.md(""" /// details | Info details type: info Some additional content. /// """) return @app.cell def _(mo): mo.md(""" /// details | Warning details type: warn This highlights something to watch out for /// """) return @app.cell def _(mo): mo.md(""" /// details | Danger details type: danger This indicates a critical warning or dangerous situation /// """) return @app.cell def _(mo): mo.md(""" /// details | Success details type: success This indicates a successful outcome or positive note /// """) return @app.cell def _(): import marimo as mo return (mo,) if __name__ == "__main__": app.run()`` #### Admonitions[¶](#admonitions "Permanent link") Highlight text using admonitions: `[](#__codelineno-5-1)/// attention | This is important. [](#__codelineno-5-2)[](#__codelineno-5-3)Pay attention to this text! [](#__codelineno-5-4)///` Source code for `examples/markdown/admonitions.py` Tip: paste this code into an empty cell, and the marimo editor will create cells for you `import marimo __generated_with = "0.17.4" app = marimo.App() @app.cell(hide_code=True) def _(mo): mo.md(r""" Use **admonitions** in markdown to bring attention to text. Here are some examples. """) return @app.cell def _(mo): mo.md(""" /// admonition | Heads up. Here's some information. /// """) return @app.cell def _(mo): mo.md(""" /// attention | Attention! This is important. /// """) return @app.cell def _(): import marimo as mo return (mo,) if __name__ == "__main__": app.run()` #### Emoji[¶](#emoji "Permanent link") Use `:emoji:` syntax to add emojis; for example, `:rocket:` creates 🚀. ### Static files[¶](#static-files "Permanent link") marimo supports serving static files from a `public/` folder located next to your notebook. This is useful for including images or other static assets in your notebook. To use files from the public folder, create a `public` directory next to your notebook and reference files using the `public/` path prefix: `[](#__codelineno-6-1)mo.md( [](#__codelineno-6-2) ''' [](#__codelineno-6-3) [](#__codelineno-6-4) [](#__codelineno-6-5) or [](#__codelineno-6-6) [](#__codelineno-6-7) ![alt text](public/image.png) [](#__codelineno-6-8) ''' [](#__codelineno-6-9))` For security reasons: * Only files within the `public` directory can be accessed * Symlinks are not followed * Path traversal attempts (e.g., `../`) are blocked Layout[¶](#layout "Permanent link") ----------------------------------- The marimo library also comes with elements for laying out outputs, including [`mo.hstack`](https://docs.marimo.io/api/layouts/stacks/#marimo.hstack " marimo.hstack"), [`mo.vstack`](https://docs.marimo.io/api/layouts/stacks/#marimo.vstack " marimo.vstack"), [`mo.accordion`](https://docs.marimo.io/api/layouts/accordion/#marimo.accordion " marimo.accordion"), [`mo.ui.tabs`](https://docs.marimo.io/api/inputs/tabs/#marimo.ui.tabs " marimo.ui.tabs"), [`mo.sidebar`](https://docs.marimo.io/api/layouts/sidebar/#marimo.sidebar " marimo.sidebar"), [`mo.nav_menu`](https://docs.marimo.io/api/inputs/nav_menu/#marimo.nav_menu " marimo.nav_menu"), [`mo.ui.table`](https://docs.marimo.io/api/inputs/table/#marimo.ui.table " marimo.ui.table"), and [many more](https://docs.marimo.io/api/layouts/). Progress bars[¶](#progress-bars "Permanent link") ------------------------------------------------- Use [`mo.status.progress_bar`](https://docs.marimo.io/api/status/#marimo.status.progress_bar " marimo.status.progress_bar") and [`mo.status.spinner`](https://docs.marimo.io/api/status/#marimo.status.spinner " marimo.status.spinner") to create progress indicators: `[](#__codelineno-7-1)# mo.status.progress_bar is similar to TQDM [](#__codelineno-7-2)for i in mo.status.progress_bar(range(10)): [](#__codelineno-7-3) print(i)` marimo comes with functions to display media, including images, audio, video, pdfs, and more. See the [API docs](https://docs.marimo.io/api/media/) for more info. Inspecting objects[¶](#inspecting-objects "Permanent link") ----------------------------------------------------------- marimo has built-in formatters for many objects, but sometimes the default representation isn't useful (e.g., ``). In these cases, use [`mo.inspect()`](https://docs.marimo.io/api/miscellaneous/#marimo.inspect " marimo.inspect") to explore an object's attributes, methods, and documentation as an output. See the [API docs](https://docs.marimo.io/api/outputs/#object-inspection) for more details. Imperatively adding outputs[¶](#imperatively-adding-outputs "Permanent link") ----------------------------------------------------------------------------- While a cell's output is its last expression, it can at times be helpful to imperatively add to the output area while a cell is running. marimo provides utility functions like [`mo.output.append`](https://docs.marimo.io/api/outputs/#marimo.output.append " marimo.output.append") for accomplishing this; see the [API docs](https://docs.marimo.io/api/outputs/) for more information. Console Outputs[¶](#console-outputs "Permanent link") ----------------------------------------------------- Console outputs, such as print statements, show up below a cell in the console output area; they are not included in the output area or app view by default. To include console outputs in the cell output area, use [`mo.redirect_stdout`](https://docs.marimo.io/api/outputs/#marimo.redirect_stdout " marimo.redirect_stdout") or [`mo.redirect_stderr`](https://docs.marimo.io/api/outputs/#marimo.redirect_stderr " marimo.redirect_stderr"): `[](#__codelineno-8-1)with mo.redirect_stdout(): [](#__codelineno-8-2) print("Hello, world!")` marimo also includes utility functions for [capturing standard out](https://docs.marimo.io/api/outputs/#marimo.capture_stdout " marimo.capture_stdout") and [standard error](https://docs.marimo.io/api/outputs/#marimo.capture_stderr " marimo.capture_stderr") without redirecting them. See the [API docs](https://docs.marimo.io/api/outputs/#console-outputs) for more. Threading[¶](#threading "Permanent link") ----------------------------------------- To create a thread that can reliably communicate outputs to the frontend, use [`mo.Thread`](https://docs.marimo.io/api/control_flow/#marimo.Thread " marimo.Thread"), which has exactly the same API as as `threading.Thread`. ### Cleaning up your thread[¶](#cleaning-up-your-thread "Permanent link") When the cell that spawned a [`mo.Thread`](https://docs.marimo.io/api/control_flow/#marimo.Thread " marimo.Thread") is invalidated (re-run, deleted, interrupted, or otherwise errored), the thread's `should_exit` property will evaluate to `True`, at which point it is your responsibility to clean up your thread. You can retrieve the current [`mo.Thread`](https://docs.marimo.io/api/control_flow/#marimo.Thread " marimo.Thread") with [`mo.current_thread`](https://docs.marimo.io/api/control_flow/#marimo.current_thread " marimo.current_thread"). **Example.** `[](#__codelineno-9-1)def target(): [](#__codelineno-9-2) import marimo as mo [](#__codelineno-9-3) [](#__codelineno-9-4) thread = mo.current_thread() [](#__codelineno-9-5) while not thread.should_exit: [](#__codelineno-9-6) ...` ### Patching threads created by third-party code[¶](#patching-threads-created-by-third-party-code "Permanent link") If you need to forward outputs from threads spawned by third-party code, try patching `threading.Thread`: `[](#__codelineno-10-1)import threading [](#__codelineno-10-2)import marimo as mo [](#__codelineno-10-3)[](#__codelineno-10-4)threading.Thread = mo.Thread` This however may leak threads, since the patched threads won't know to check the `mo.Thread`'s `should_exit` property. Expensive notebooks - marimo https://docs.marimo.io/guides/expensive_notebooks/ Working with expensive notebooks[¶](#working-with-expensive-notebooks "Permanent link") --------------------------------------------------------------------------------------- marimo provides tools to control when cells run. Use these tools to prevent expensive cells, which may call APIs or take a long time to run, from accidentally running. Stop execution with `mo.stop`[¶](#stop-execution-with-mostop "Permanent link") ------------------------------------------------------------------------------ Use [`mo.stop`](https://docs.marimo.io/api/control_flow/#marimo.stop " marimo.stop") to stop a cell from executing if a condition is met: `[](#__codelineno-0-1)# if condition is True, the cell will stop executing after mo.stop() returns [](#__codelineno-0-2)mo.stop(condition) [](#__codelineno-0-3)# this won't be called if condition is True [](#__codelineno-0-4)expensive_function_call()` Use [`mo.stop`](https://docs.marimo.io/api/control_flow/#marimo.stop " marimo.stop") with [`mo.ui.run_button()`](https://docs.marimo.io/api/inputs/run_button/#marimo.ui.run_button " marimo.ui.run_button") to require a button press for expensive cells: Configure how marimo runs cells[¶](#configure-how-marimo-runs-cells "Permanent link") ------------------------------------------------------------------------------------- ### Disable cell autorun[¶](#disable-cell-autorun "Permanent link") If you habitually work with very expensive notebooks, you can [disable automatic execution](https://docs.marimo.io/guides/configuration/runtime_configuration/#disable-autorun-on-cell-change-lazy-execution). When automatic execution is disabled, when you run a cell, marimo marks dependent cells as stale instead of running them automatically. ### Disable autorun on startup[¶](#disable-autorun-on-startup "Permanent link") marimo autoruns notebooks on startup, with `marimo edit notebook.py` behaving analogously to `python notebook.py`. This can also be disabled through the [notebook settings](https://docs.marimo.io/guides/configuration/runtime_configuration/#on-startup). ### Disable individual cells[¶](#disable-individual-cells "Permanent link") marimo lets you temporarily disable cells from automatically running. This is helpful when you want to edit one part of a notebook without triggering execution of other parts. See the [reactivity guide](https://docs.marimo.io/guides/reactivity/#disabling-cells) for more info. Manage memory[¶](#manage-memory "Permanent link") ------------------------------------------------- Here are a few tips for managing the memory consumption of your notebooks, on host or GPU. ### Wrap intermediate computations in functions[¶](#wrap-intermediate-computations-in-functions "Permanent link") By default, global variables live in the kernel memory. Intermediate variables that are defined in functions are cleaned up automatically. For example, if `X` is a temporary: **Do this:** `[](#__codelineno-2-1)def _(): [](#__codelineno-2-2) X = torch.randn(1e4, 1e4, device='cuda') [](#__codelineno-2-3) Y = f(X) [](#__codelineno-2-4) return Y` **Don't do this:** `[](#__codelineno-3-1)X = torch.randn(1e4, 1e4, device='cuda') [](#__codelineno-3-2)Y = f(X) [](#__codelineno-3-3)# X still lives in program memory!` ### Use `del` to remove variables from kernel memory[¶](#use-del-to-remove-variables-from-kernel-memory "Permanent link") Use the `del` operator to remove variables from kernel memory. **In a single cell.** Prefer deleting variables in the cell they were defined in. For example, if `X` is a temporary that you don't need after computing `Y`: `[](#__codelineno-4-1)X = torch.randn(1e4, 1e4, device='cuda') [](#__codelineno-4-2)Y = f(X) [](#__codelineno-4-3)del X` **In another cell.** Sometimes, computations are spread across multiple cells, and you only realize later on that you need to free memory that you've already allocated. In such cases you can still use the `del` keyword. For example: `[](#__codelineno-5-1)data = load_large_dataset()` marimo inserts control dependences to make sure that variables are not deleted before they are used. When `del` is used to delete a variable that was defined in a another cell, the cell where `del` was used becomes a child of all other cells that reference that variable. In this case, that means marimo knows to run the third cell after the second cell, since the second cell references `data` and the third cell deletes it. However, once `data` is deleted, attempting to manually run the second cell will raise a `NameError`, and you'll need to re-run the defining cell in order to get your notebook back to a consistent state. Automatically snapshot outputs as HTML or IPYNB[¶](#automatically-snapshot-outputs-as-html-or-ipynb "Permanent link") --------------------------------------------------------------------------------------------------------------------- To keep a record of your cell outputs while working on your notebook, you can configure notebooks to automatically save as HTML or ipynb through the notebook menu (these files are saved in addition to the notebook's `.py` file). Snapshots are saved to a folder called `__marimo__` in the notebook directory. Learn more about exporting notebooks in our [exporting guide](https://docs.marimo.io/guides/exporting/). Cache expensive computations[¶](#cache-expensive-computations "Permanent link") ------------------------------------------------------------------------------- marimo provides two decorators to cache the return values of expensive functions: 1. In-memory caching with [`mo.cache`](https://docs.marimo.io/api/caching/#marimo.cache " marimo.cache") 2. Disk caching with [`mo.persistent_cache`](https://docs.marimo.io/api/caching/#marimo.persistent_cache " marimo.persistent_cache") Both utilities can be used as decorators or context managers. `mo.cache``mo.persistent_cache` `[](#__codelineno-8-1)import marimo as mo [](#__codelineno-8-2)[](#__codelineno-8-3)@mo.cache [](#__codelineno-8-4)def compute_embedding(data: str, embedding_dimension: int, model: str) -> np.ndarray: [](#__codelineno-8-5) ...` `[](#__codelineno-9-1)import marimo as mo [](#__codelineno-9-2)[](#__codelineno-9-3)@mo.persistent_cache [](#__codelineno-9-4)def compute_embedding(data: str, embedding_dimension: int, model: str) -> np.ndarray [](#__codelineno-9-5) ...` See our [guide on caching](https://docs.marimo.io/api/caching/) for details, including how the cache key is constructed, and limitations. Lazy-load expensive UIs[¶](#lazy-load-expensive-uis "Permanent link") --------------------------------------------------------------------- Lazily render UI elements that are expensive to compute using `marimo.lazy`. For example, `[](#__codelineno-10-1)import marimo as mo [](#__codelineno-10-2)[](#__codelineno-10-3)data = db.query("SELECT * FROM data") [](#__codelineno-10-4)mo.lazy(mo.ui.table(data))` In this example, `mo.ui.table(data)` will not be rendered on the frontend until is it in the viewport. For example, an element can be out of the viewport due to scroll, inside a tab that is not selected, or inside an accordion that is not open. However, in this example, data is eagerly computed, while only the rendering of the table is lazy. It is possible to lazily compute the data as well: see the next example. `[](#__codelineno-11-1)import marimo as mo [](#__codelineno-11-2)[](#__codelineno-11-3)def expensive_component(): [](#__codelineno-11-4) import time [](#__codelineno-11-5) time.sleep(1) [](#__codelineno-11-6) data = db.query("SELECT * FROM data") [](#__codelineno-11-7) return mo.ui.table(data) [](#__codelineno-11-8)[](#__codelineno-11-9)accordion = mo.accordion({ [](#__codelineno-11-10) "Charts": mo.lazy(expensive_component) [](#__codelineno-11-11)})` In this example, we pass a function to `mo.lazy` instead of a component. This function will only be called when the user opens the accordion. In this way, `expensive_component` lazily computed and we only query the database when the user needs to see the data. This can be useful when the data is expensive to compute and the user may not need to see it immediately. Migrate from Jupyter - marimo https://docs.marimo.io/guides/coming_from/jupyter/ Coming from Jupyter[¶](#coming-from-jupyter "Permanent link") ------------------------------------------------------------- If you're coming from Jupyter, here are a few tips to help you adapt to marimo notebooks. How marimo runs cells[¶](#how-marimo-runs-cells "Permanent link") ----------------------------------------------------------------- The biggest difference between marimo and Jupyter is the [execution model](https://docs.marimo.io/guides/reactivity/). A **Jupyter** notebook is a **REPL**: you execute blocks of code one at a time, and Jupyter has no understanding of how different blocks are related to each other. As a result a Jupyter notebook can easily accumulate **"hidden state"** (and hidden bugs) --- you might accidentally execute cells out of order, or you might run (or delete) a cell but forget to re-run cells that depended on its variables. Because of this, Jupyter notebooks suffer from a [reproducibility crisis](https://docs.marimo.io/faq/#faq-problems), with over a third of Jupyter notebooks on GitHub failing to reproduce. Unlike Jupyter, **marimo** notebooks understand how different blocks of code are related to each other, modeling your code as a graph on cells based on variable declarations and references. This eliminates hidden state, and it's also what enables marimo notebooks to be reused as apps and scripts. **By default, if you run a cell in marimo, all other cells that read its variables run automatically.** While this ensures that your code and outputs are in sync, it can take some time getting used to. **Here are some tips and tools to help you adapt to marimo's execution model.** ### Configure marimo's runtime[¶](#configure-marimos-runtime "Permanent link") [Configure marimo's runtime](https://docs.marimo.io/guides/configuration/runtime_configuration/) to not autorun on startup or on cell execution. Even when autorun is disabled, marimo still tracks dependencies across cells, marking dependents of a cell as stale when you run it. You can click a single button to run all your stale cells and bring your notebook back up-to-date. ### Stop execution with `mo.stop`[¶](#stop-execution-with-mostop "Permanent link") Use [`mo.stop`](https://docs.marimo.io/api/control_flow/#marimo.stop " marimo.stop") to stop a cell from executing if a condition is met: `[](#__codelineno-0-1)# if condition is True, the cell will stop executing after mo.stop() returns [](#__codelineno-0-2)mo.stop(condition) [](#__codelineno-0-3)# this won't be called if condition is True [](#__codelineno-0-4)expensive_function_call()` Use [`mo.stop()`](https://docs.marimo.io/api/control_flow/#marimo.stop " marimo.stop") in conjunction with [`mo.ui.run_button()`](https://docs.marimo.io/api/inputs/run_button/#marimo.ui.run_button " marimo.ui.run_button") to require a button press for expensive cells: ### Working with expensive notebooks[¶](#working-with-expensive-notebooks "Permanent link") For more tips on adapting to marimo's execution model, see our guide on [working with expensive notebooks](https://docs.marimo.io/guides/expensive_notebooks/). Redefining variables[¶](#redefining-variables "Permanent link") --------------------------------------------------------------- marimo "compiles" your notebook cells into a directed graph on cells, linked by variable declarations and references, reusing this graph to run your notebook as a script or app. For marimo's compilation to work, the same variable cannot be defined in multiple cells; otherwise, marimo wouldn't know what order to run cells in. To adapt to the restriction, we suggest: 1. Encapsulating code into functions when possible, to minimize the number of global variables. 2. Prefixing temporary variables with an underscore (`_my_temporary`), which makes the variable **local** to a cell. 3. Mutating variables in the cell that defines them. When working with **dataframes**, you might be used to redefining the same `df` variable in multiple cells. That won't work in marimo. Instead, try merging the cells into a single cell: _Don't_ do this: `[](#__codelineno-2-1)df = pd.DataFrame({"my_column": [1, 2]})` `[](#__codelineno-3-1)df["another_column"] = [3, 4]` _Instead_, do this: `[](#__codelineno-4-1)df = pd.DataFrame({"my_column": [1, 2]}) [](#__codelineno-4-2)df["another_column"] = [3, 4]` If you do need to transform a dataframe across multiple cells, you can alias the dataframe: `[](#__codelineno-5-1)df = pd.DataFrame({"my_column": [1, 2]})` `[](#__codelineno-6-1)augmented_df = df [](#__codelineno-6-2)augmented_df["another_column"] = [3, 4]` marimo's file format[¶](#marimos-file-format "Permanent link") -------------------------------------------------------------- marimo stores notebooks as Python, not JSON. This lets you version notebooks with git, [execute them as scripts](https://docs.marimo.io/guides/scripts/), and import named cells into other Python files. However, it does mean that your notebook outputs (e.g., plots) are not stored in the file. If you'd like to keep a visual record of your notebook work, [enable the "Auto-download as HTML/IPYNB" setting](https://docs.marimo.io/guides/configuration/), which will periodically snapshot your notebook as HTML or IPYNB to a `__marimo__` folder in the notebook directory. ### Converting Jupyter notebooks to marimo notebooks[¶](#converting-jupyter-notebooks-to-marimo-notebooks "Permanent link") Convert Jupyter notebooks to marimo notebooks at the command-line: `[](#__codelineno-7-1)marimo convert your_notebook.ipynb -o your_notebook.py` ### Converting Python scripts to marimo notebooks[¶](#converting-python-scripts-to-marimo-notebooks "Permanent link") marimo can also convert regular Python scripts to marimo notebooks: `[](#__codelineno-8-1)marimo convert your_script.py -o your_notebook.py` This supports: - **py:percent format**: If your script uses `# %%` cell markers, marimo will convert it to a multi-cell notebook (requires jupytext) - **Regular Python scripts**: Scripts without cell markers are converted to a single-cell notebook For py:percent conversion with uv: `[](#__codelineno-9-1)uvx --with=jupytext marimo convert your_script.py -o your_notebook.py` ### Exporting marimo notebooks to Jupyter notebooks[¶](#exporting-marimo-notebooks-to-jupyter-notebooks "Permanent link") Export to an `ipynb` file with `[](#__codelineno-10-1)marimo export ipynb notebook.py -o notebook.ipynb` Note that some marimo library functions, including UI elements, won't work in Jupyter notebooks. Magic commands[¶](#magic-commands "Permanent link") --------------------------------------------------- Because marimo notebooks are just Python (improving maintainability), marimo doesn't support IPython magic commands or `!`\-prefixed console commands. Here are some alternatives. ### Run console commands with subprocess.run[¶](#run-console-commands-with-subprocessrun "Permanent link") To run a console command, use Python's [subprocess.run](https://docs.python.org/3/library/subprocess.html#subprocess.run): `[](#__codelineno-11-1)import subprocess [](#__codelineno-11-2)[](#__codelineno-11-3)# run: "ls -l" [](#__codelineno-11-4)subprocess.run(["ls", "-l"])` ### Common magic commands replacements[¶](#common-magic-commands-replacements "Permanent link") | Magic Command | Replacement | | --- | --- | | %cd | `os.chdir()`, see also [`mo.notebook_dir()`](https://docs.marimo.io/api/miscellaneous/#marimo.notebook_dir " marimo.notebook_dir") | | %clear | Right-click or toggle the cell actions | | %debug | Python's built-in debugger: `breakpoint()` | | %env | `os.environ` | | %load | N/A - use Python imports | | %load\_ext | N/A | | %autoreload | marimo's [module autoreloader](https://docs.marimo.io/guides/editor_features/module_autoreloading/) | | %matplotlib | marimo auto-displays plots | | %pwd | `os.getcwd()` | | %pip | Use marimo's [built-in package management](https://docs.marimo.io/guides/editor_features/package_management/) | | %who\_ls | `dir()`, `globals()`, [`mo.refs()`](https://docs.marimo.io/api/miscellaneous/#marimo.refs " marimo.refs"), [`mo.defs()`](https://docs.marimo.io/api/miscellaneous/#marimo.defs " marimo.defs") | | %system | `subprocess.run()` | | %%time | `time.perf_counter()` or Python's timeit module | | %%timeit | Python's timeit module | | %%writefile | `with open("file.txt", "w") as f: f.write()` | | %%capture | [`mo.capture_stdout()`](https://docs.marimo.io/api/outputs/#marimo.capture_stdout " marimo.capture_stdout"), [`mo.capture_stderr()`](https://docs.marimo.io/api/outputs/#marimo.capture_stderr " marimo.capture_stderr") | | %%html | [`mo.Html()`](https://docs.marimo.io/api/html/#marimo.Html " marimo.Html dataclass ") or [`mo.md()`](https://docs.marimo.io/api/markdown/#marimo.md " marimo.md") | | %%latex | [`mo.md(r'$$...$$')`](https://docs.marimo.io/api/markdown/#marimo.md " marimo.md") | ### Installing packages with marimo's package manager[¶](#installing-packages-with-marimos-package-manager "Permanent link") Use marimo's package management sidebar panel to install packages to your current environment. Learn more in our [package management guide](https://docs.marimo.io/guides/editor_features/package_management/). Interactive guide[¶](#interactive-guide "Permanent link") --------------------------------------------------------- This guide contains additional tips to help you adapt to marimo. Fun fact: the guide is itself a marimo notebook! Understanding errors - marimo https://docs.marimo.io/guides/understanding_errors/ marimo imposes a few constraints on your notebook code: * no multiply defined variables: each variable can be defined in only one cell * no cycles: if one cell declares variable `a` and reads `b`, then another cannot declare `b` and read `a`. * no `import *`: importing all symbols from a library is not allowed Why these constraints? These constraints let marimo work its magic, making your notebooks: * **reproducible**, with a well-defined execution order, no hidden state, and no hidden bugs; * **executable** as a script; * **interactive** with UI elements that work without callbacks; * **shareable as a web app**, with far better performance than streamlit. As a bonus, you'll find that you end up with cleaner, reusable code. When a cell violates any of these constraints, marimo doesn't run it and instead reports an error. In these guides, we explain these errors and provide tips for how to work around them. These errors might be surprising at first, but spend just a bit of time with marimo and adhering to these constraints will become second nature — and you'll get used to writing error-free code by default. Lint Rules[¶](#lint-rules "Permanent link") ------------------------------------------- marimo includes a comprehensive linting system that automatically detects these constraints and other code quality issues. The linter can help you identify and fix problems before they cause runtime errors. Run the linter using: See the [Lint Rules](https://docs.marimo.io/guides/lint_rules/) guide for a complete list of rules and detailed explanations. | Guide | Description | | --- | --- | | [Multiple definitions](https://docs.marimo.io/guides/understanding_errors/multiple_definitions/) | How to deal with variables defined in multiple cells | | [Import `*`](https://docs.marimo.io/guides/understanding_errors/import_star/) | Why you can't use `import *` | | [Cycles](https://docs.marimo.io/guides/understanding_errors/cycles/) | How to resolve cycle errors | | [setup](https://docs.marimo.io/guides/understanding_errors/setup/) | How to enable top level definitions | Cycles - marimo https://docs.marimo.io/guides/understanding_errors/cycles/ You're probably on this page because you just saw an error like this one: marimo raises this error when a cell is involved in a cycle on variables. In this example, the first cell declares `a` and reads `b`, while the second cell declares `b` and reads `a`. Why can't I have cycles?[¶](#why-cant-i-have-cycles "Permanent link") --------------------------------------------------------------------- marimo parses your cells to understand the order in which they run: run a cell, and cells that refer to its defined variables need to run afterward. With a cycle, the execution order becomes ambiguous, while also introducing an infinite loop. **What do I get in return?** By accepting this constraint on variables, marimo makes your notebooks: * **reproducible**, with a well-defined execution order, no hidden state, and no hidden bugs; * **executable** as a script; * **interactive** with UI elements that work without callbacks; * **shareable as a web app**, with far better performance than streamlit. As a bonus, you'll find that you end up with cleaner, reusable code. **How do I read the error message?** In the error message, each line says which cell defines a variable and which cell reads a variable. For example, `cell-0 -> a` means `cell-0` defines `a`, and `a -> cell-1` means `cell-1` reads `a`. Similarly, `cell-1 -> b` means `cell-1` defines `b`, and `b -> cell-0` means `cell-0` reads `b`. This creates the cycle from `cell-0 -> cell-1 -> cell-0`. How do I fix this error?[¶](#how-do-i-fix-this-error "Permanent link") ---------------------------------------------------------------------- Cycles usually indicate that your notebook has a bug. Still, you can fix the error by merging the cells involved in the cycle into a single cell: Import star - marimo https://docs.marimo.io/guides/understanding_errors/import_star/ Star imports[¶](#star-imports "Permanent link") ----------------------------------------------- You're probably on this page because you just saw an error like this one: marimo raises this error you attempt to use `import *`. In this example, `x` was already defined, and the subsequent cell raised an error when we tried to run it. In your case, perhaps your variable is a loop variable (`i`), a dataframe (`df`), or a plot (`fig`, `ax`). Why can't I use `*` imports?[¶](#why-cant-i-use-imports "Permanent link") ------------------------------------------------------------------------- Star imports are incompatible with marimo's git-friendly file format and reproducible reactive execution: * marimo's Python file format stores code in functions, so notebooks can be imported as regular Python modules without executing all their code. But Python disallows `import *` everywhere except at the top-level of a module. * Star imports would also silently add names to globals, which would be incompatible with [reactive execution](https://docs.marimo.io/guides/reactivity/). Even Python's [official style guide](https://peps.python.org/pep-0008/) discourages the use of `import *`, writing: > Wildcard imports (from import \*) should be avoided, as they make it unclear which names are present in the namespace, confusing both readers and many automated tools. **What do I get in return?** By accepting this constraint on imports, marimo makes your notebooks: * **reproducible**, with a well-defined execution order, no hidden state, and no hidden bugs; * **executable** as a script; * **interactive** with UI elements that work without callbacks; * **shareable as a web app**, with far better performance than streamlit. As a bonus, you'll find that you end up with cleaner, reusable code. How do I fix this error?[¶](#how-do-i-fix-this-error "Permanent link") ---------------------------------------------------------------------- Fixing this error is simple: just import the module, and use `.` notation to access its members. instead of Multiple definitions - marimo https://docs.marimo.io/guides/understanding_errors/multiple_definitions/ You're probably on this page because you just saw an error like this one: marimo raises this error when a variable is defined in multiple cells. In this example, `x` was already defined, and the subsequent cell raised an error when we tried to run it. In your case, perhaps your variable is a loop variable (`i`), a dataframe (`df`), or a plot (`fig`, `ax`). Watch our YouTube explainer Why can't I redefine variables?[¶](#why-cant-i-redefine-variables "Permanent link") ----------------------------------------------------------------------------------- **Understanding the error message.** The error message tells you which other cells defined the multiply defined variable. You can click on the cell name, and marimo will highlight it. **Why can't I redefine variables?** marimo guarantees that the code on the page matches the outputs you see by determining a deterministic execution order on cells; when one cell runs, marimo knows which others should run. But if two cells defined `x`, and a third showed `x`, the output of the third cell would be ambiguous, depending on which of the defining cells ran first (should it be `0` or `1`?). That's a problem because it creates [hidden state and hidden bugs](https://docs.marimo.io/guides/coming_from/jupyter/), and it's part of the reason why [over 96% of Jupyter notebooks on GitHub aren't reproducible](https://leomurta.github.io/papers/pimentel2019a.pdf). **What do I get in return?** By accepting this constraint on variables, marimo makes your notebooks: * **reproducible**, with a well-defined execution order, no hidden state, and no hidden bugs; * **executable** as a script; * **interactive** with UI elements that work without callbacks; * **shareable as a web app**, with far better performance than streamlit. As a bonus, you'll find that you end up with cleaner, reusable code. How do I fix this error?[¶](#how-do-i-fix-this-error "Permanent link") ---------------------------------------------------------------------- You have a few options. ### Use local variables[¶](#use-local-variables "Permanent link") In marimo, variables prefixed with an underscore (`_x` or `_i`) are made local to a cell, and can be redefined across multiple cells. Use this in a pinch, but prefer encapsulating code in functions. ### Encapsulate code in a function[¶](#encapsulate-code-in-a-function "Permanent link") Python provides local scope through functions: if the variable that was redefined is meant to be a temporary variable, then you can make it local to the cell by encapsulating the code in a function. If any of the cell's variables are not meant to be local, or are outputs meant to be displayed, just return them from the function. In general, we recommend writing modular code with meaningful functions. But, in a pinch, just declare an anonymous function like this one to get a "local scope": `[](#__codelineno-1-1)def _(): [](#__codelineno-1-2) import matplotlib.pyplot as plt [](#__codelineno-1-3) fig, ax = plt.subplots() [](#__codelineno-1-4) ax.plot([1, 2]) [](#__codelineno-1-5) return ax [](#__codelineno-1-6)[](#__codelineno-1-7)_()` That's what clicking on the "Fix: Wrap in a function" button does. Note the function `_()` is local to the cell. ### Merge cells[¶](#merge-cells "Permanent link") Often you can simply merge the cells that define the same variable into a single cell. To incrementally show outputs in the cell, use [`mo.output.append`](https://docs.marimo.io/api/outputs/#marimo.output.append " marimo.output.append") or `print()`. ### Chain dataframe methods[¶](#chain-dataframe-methods "Permanent link") When working with dataframes, instead of splitting up operations across multiple cells, chain operations in a single cell. This is especially ergonomic when using [Polars](https://docs.pola.rs/), Daft, or other modern dataframe libraries that support lazy execution. Setup References - marimo https://docs.marimo.io/guides/understanding_errors/setup/ You're probably on this page because you just saw an error like this one: marimo raises this error when the setup cell references variables defined in other cells. In the example above, `image` is defined elsewhere in the notebook, and hence cannot be referenced. Why can't I refer to variables?[¶](#why-cant-i-refer-to-variables "Permanent link") ----------------------------------------------------------------------------------- The setup cell special: it runs before all other cells run, in order to provide symbols that [top-level functions and classes](https://docs.marimo.io/guides/reusing_functions/) can use. That's why it can't reference variables defined by other cells. How do I fix this error?[¶](#how-do-i-fix-this-error "Permanent link") ---------------------------------------------------------------------- Define all needed variables in the setup cell. Or, if this code does not need to run before all other cells (if you are not using top-level functions or classes), simply move your code to a regular cell. Lint Rules - marimo https://docs.marimo.io/guides/lint_rules/ marimo includes a comprehensive linting system that helps you write better, more reliable notebooks. The linter checks for various issues that could prevent your notebook from running correctly or cause confusion. How to Use[¶](#how-to-use "Permanent link") ------------------------------------------- You can run the linter using the CLI: `[](#__codelineno-0-1)# Check all notebooks in current directory [](#__codelineno-0-2)marimo check . [](#__codelineno-0-3)[](#__codelineno-0-4)# Check specific files [](#__codelineno-0-5)marimo check notebook1.py notebook2.py [](#__codelineno-0-6)[](#__codelineno-0-7)# Auto-fix fixable issues [](#__codelineno-0-8)marimo check --fix .` Rule Categories[¶](#rule-categories "Permanent link") ----------------------------------------------------- marimo's lint rules are organized into three main categories based on their severity: ### 🚨 Breaking Rules[¶](#breaking-rules "Permanent link") These errors prevent notebook execution. | Code | Name | Description | Fixable | | --- | --- | --- | --- | | [MB001](https://docs.marimo.io/guides/lint_rules/rules/unparsable_cells/) | unparsable-cells | Cell contains unparsable code | ❌ | | [MB002](https://docs.marimo.io/guides/lint_rules/rules/multiple_definitions/) | multiple-definitions | Multiple cells define the same variable | ❌ | | [MB003](https://docs.marimo.io/guides/lint_rules/rules/cycle_dependencies/) | cycle-dependencies | Cells have circular dependencies | ❌ | | [MB004](https://docs.marimo.io/guides/lint_rules/rules/setup_cell_dependencies/) | setup-cell-dependencies | Setup cell cannot have dependencies | ❌ | | [MB005](https://docs.marimo.io/guides/lint_rules/rules/invalid_syntax/) | invalid-syntax | Cell contains code that throws a SyntaxError on compilation | ❌ | ### ⚠️ Runtime Rules[¶](#runtime-rules "Permanent link") These issues may cause runtime problems. | Code | Name | Description | Fixable | | --- | --- | --- | --- | | [MR001](https://docs.marimo.io/guides/lint_rules/rules/self_import/) | self-import | Importing a module with the same name as the file | ❌ | ### ✨ Formatting Rules[¶](#formatting-rules "Permanent link") These are style and formatting issues. | Code | Name | Description | Fixable | | --- | --- | --- | --- | | [MF001](https://docs.marimo.io/guides/lint_rules/rules/general_formatting/) | general-formatting | General formatting issues with the notebook format. | 🛠️ | | [MF002](https://docs.marimo.io/guides/lint_rules/rules/parse_stdout/) | parse-stdout | Parse captured stdout during notebook loading | ❌ | | [MF003](https://docs.marimo.io/guides/lint_rules/rules/parse_stderr/) | parse-stderr | Parse captured stderr during notebook loading | ❌ | | [MF004](https://docs.marimo.io/guides/lint_rules/rules/empty_cells/) | empty-cells | Empty cells that can be safely removed. | ⚠️ | | [MF005](https://docs.marimo.io/guides/lint_rules/rules/sql_parse_error/) | sql-parse-error | SQL parsing errors during dependency analysis | ❌ | | [MF006](https://docs.marimo.io/guides/lint_rules/rules/misc_log_capture/) | misc-log-capture | Miscellaneous log messages during processing | ❌ | | [MF007](https://docs.marimo.io/guides/lint_rules/rules/markdown_indentation/) | markdown-indentation | Markdown cells in `mo.md()` should be dedented. | 🛠️ | Legend[¶](#legend "Permanent link") ----------------------------------- * 🛠️ = Automatically fixable with `marimo check --fix` * ⚠️ = Fixable with `marimo check --fix --unsafe-fixes` (may change code behavior) * ❌ = Not automatically fixable Configuration[¶](#configuration "Permanent link") ------------------------------------------------- Most lint rules are enabled by default. You can configure the linter behavior through marimo's configuration system. * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) - Detailed explanations of common marimo errors * [CLI Reference](https://docs.marimo.io/cli/) - Complete CLI documentation including `marimo check` Unparsable cells - marimo https://docs.marimo.io/guides/lint_rules/rules/unparsable_cells/ 🚨 **Breaking** ❌ Not Fixable MB001: Cell contains unparsable code. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Identifies cells that cannot be parsed into valid Python AST nodes, indicating fundamental syntax or encoding problems that prevent the notebook from being loaded. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Unparsable cells prevent the notebook from running as a script and will throw errors when executed in notebook mode. While marimo can still open the notebook, these cells cannot be run until the parsing issues are resolved. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Cell with encoding issues or corrupt data [](#__codelineno-0-2)x = 1 \x00\x01\x02 # Binary data in source` **Problematic:** `[](#__codelineno-1-1)# Cell with fundamental syntax errors [](#__codelineno-1-2)def func( [](#__codelineno-1-3) # Missing closing parenthesis and body` **Solution:** `[](#__codelineno-2-1)# Fix syntax errors and encoding issues [](#__codelineno-2-2)def func(): [](#__codelineno-2-3) return 42` References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) Debugging notebooks - marimo https://docs.marimo.io/guides/debugging/ Debugging in marimo[¶](#debugging-in-marimo "Permanent link") ------------------------------------------------------------- ### Using pdb in marimo notebooks[¶](#using-pdb-in-marimo-notebooks "Permanent link") 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. Type `help` in the debugger for a list of commands: `[](#__codelineno-0-1)Documented commands (type help ): [](#__codelineno-0-2)======================================== [](#__codelineno-0-3)EOF cl disable ignore n return u where [](#__codelineno-0-4)a clear display interact next retval unalias [](#__codelineno-0-5)alias commands down j p run undisplay [](#__codelineno-0-6)args condition enable jump pp rv unt [](#__codelineno-0-7)b cont exceptions l q s until [](#__codelineno-0-8)break continue exit list quit source up [](#__codelineno-0-9)bt d h ll r step w [](#__codelineno-0-10)c debug help longlist restart tbreak whatis [](#__codelineno-0-11)[](#__codelineno-0-12)Miscellaneous help topics: [](#__codelineno-0-13)========================== [](#__codelineno-0-14)exec pdb` Note Since this block is runnable, you can test the debugger directly Tip Click the little bug icon in the stack trace to add breakpoints. Clicking on the cell link will also take you to the cell where the error occurred. ### Postmortem debugging[¶](#postmortem-debugging "Permanent link") 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: Note Other tools like the following will also work in marimo notebooks: `[](#__codelineno-2-1) import code [](#__codelineno-2-2) code.interact() [](#__codelineno-2-3) return` Danger Remember to continue or quit the debugger to avoid hanging the notebook! Tips for debugging marimo notebooks with AI[¶](#tips-for-debugging-marimo-notebooks-with-ai "Permanent link") ------------------------------------------------------------------------------------------------------------- marimo provides built-in integration with AI assistants to help debug your notebooks more effectively. ### Ask about notebook errors[¶](#ask-about-notebook-errors "Permanent link") 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. ### Best practices for AI-assisted debugging[¶](#best-practices-for-ai-assisted-debugging "Permanent link") **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](https://docs.marimo.io/guides/troubleshooting/#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[¶](#debugging-notebooks-as-a-script "Permanent link") ------------------------------------------------------------------------------------- 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. `[](#__codelineno-3-1)python -m pdb your_script.py` External IDE debugging with `debugpy`[¶](#external-ide-debugging-with-debugpy "Permanent link") ----------------------------------------------------------------------------------------------- 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[¶](#script-mode "Permanent link") You can debug marimo notebooks in VSCode using the following `launch.json`. This launch configuration will debug a marimo notebook in [script mode](https://docs.marimo.io/guides/scripts/). `[](#__codelineno-4-1){ [](#__codelineno-4-2) "version": "0.2.0", [](#__codelineno-4-3) "configurations": [ [](#__codelineno-4-4) { [](#__codelineno-4-5) "type": "python", [](#__codelineno-4-6) "request": "launch", [](#__codelineno-4-7) "name": "marimo Debug: script mode", [](#__codelineno-4-8) "program": "${file}", [](#__codelineno-4-9) "debugOptions": [ [](#__codelineno-4-10) "--ignore", "*/site-packages/marimo/*" [](#__codelineno-4-11) ] [](#__codelineno-4-12) }, [](#__codelineno-4-13) ] [](#__codelineno-4-14)}` ### Edit mode[¶](#edit-mode "Permanent link") 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](https://docs.marimo.io/guides/editor_features/watching/). 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: `[](#__codelineno-5-1){ [](#__codelineno-5-2) "version": "0.2.0", [](#__codelineno-5-3) "configurations": [ [](#__codelineno-5-4) { [](#__codelineno-5-5) "type": "debugpy", [](#__codelineno-5-6) "request": "launch", [](#__codelineno-5-7) "name": "marimo Debug: edit mode", [](#__codelineno-5-8) "program": "${file}", [](#__codelineno-5-9) "console": "integratedTerminal", [](#__codelineno-5-10) "cwd": "${workspaceFolder}", [](#__codelineno-5-11) "env": { [](#__codelineno-5-12) "MARIMO_SCRIPT_EDIT": "1" [](#__codelineno-5-13) }, [](#__codelineno-5-14) "justMyCode": false [](#__codelineno-5-15) } [](#__codelineno-5-16) ] [](#__codelineno-5-17)}` 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[¶](#debug-directly-in-vscode "Permanent link") ----------------------------------------------------------------------- Note LSP support for marimo notebooks is coming soon, along with native debug server integration. Multiple definitions - marimo https://docs.marimo.io/guides/lint_rules/rules/multiple_definitions/ 🚨 **Breaking** ❌ Not Fixable MB002: Multiple cells define the same variable. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Analyzes the dependency graph to detect variables that are defined in more than one cell, which violates marimo's fundamental constraint for reactive execution. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Multiple definitions prevent marimo from: - Determining the correct execution order - Creating a reliable dependency graph - Running notebooks as scripts - Providing consistent reactive updates This is a breaking error because it makes the notebook non-executable. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Cell 1 [](#__codelineno-0-2)x = 1 [](#__codelineno-0-3)[](#__codelineno-0-4)# Cell 2 [](#__codelineno-0-5)x = 2 # Error: x defined in multiple cells` **Solution:** `[](#__codelineno-1-1)# Cell 1 [](#__codelineno-1-2)x = 1 [](#__codelineno-1-3)[](#__codelineno-1-4)# Cell 2 [](#__codelineno-1-5)y = 2 # Use different variable name` References[¶](#references "Permanent link") ------------------------------------------- * [Multiple Definitions Guide](https://docs.marimo.io/guides/understanding_errors/multiple_definitions/) * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) Cycle dependencies - marimo https://docs.marimo.io/guides/lint_rules/rules/cycle_dependencies/ 🚨 **Breaking** ❌ Not Fixable MB003: Cells have circular dependencies. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Analyzes the dependency graph to detect circular references between cells, where cells depend on each other in a way that creates an impossible execution order. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Circular dependencies prevent marimo from: - Determining a valid execution order - Running notebooks reproducibly - Executing notebooks as scripts - Providing reliable reactive updates This is a breaking error because it makes the notebook non-executable. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Cell 1 [](#__codelineno-0-2)a = b + 1 # Reads b [](#__codelineno-0-3)[](#__codelineno-0-4)# Cell 2 [](#__codelineno-0-5)b = a + 1 # Reads a -> Cycle!` **Solution:** `[](#__codelineno-1-1)# Cell 1 [](#__codelineno-1-2)a = 1 [](#__codelineno-1-3)[](#__codelineno-1-4)# Cell 2 [](#__codelineno-1-5)b = a + 1 # Unidirectional dependency` References[¶](#references "Permanent link") ------------------------------------------- * [Cycles Guide](https://docs.marimo.io/guides/understanding_errors/cycles/) * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) Setup cell dependencies - marimo https://docs.marimo.io/guides/lint_rules/rules/setup_cell_dependencies/ 🚨 **Breaking** ❌ Not Fixable MB004: Setup cell cannot have dependencies. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Validates that the setup cell (if present) does not depend on variables defined in other cells, ensuring proper execution order. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Setup cell dependencies break marimo's execution model because: - The setup cell must run first to initialize the notebook - Dependencies on other cells would create impossible execution order - It violates the setup cell's purpose as initialization code This is a breaking error because it makes the notebook non-executable. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Setup cell [](#__codelineno-0-2)y = x + 1 # Error: setup depends on other cells [](#__codelineno-0-3)[](#__codelineno-0-4)# Cell 1 [](#__codelineno-0-5)x = 1` **Solution:** `[](#__codelineno-1-1)# Setup cell [](#__codelineno-1-2)y = 1 # Setup defines its own variables [](#__codelineno-1-3)[](#__codelineno-1-4)# Cell 1 [](#__codelineno-1-5)x = y + 1 # Other cells can use setup variables` References[¶](#references "Permanent link") ------------------------------------------- * [Setup References Guide](https://docs.marimo.io/guides/understanding_errors/setup/) * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) Syntax error - marimo https://docs.marimo.io/guides/lint_rules/rules/invalid_syntax/ MB005: invalid-syntax[¶](#mb005-invalid-syntax "Permanent link") ---------------------------------------------------------------- 🚨 **Breaking** ❌ Not Fixable MB005: Cell contains code that throws a SyntaxError on compilation. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Attempts to compile each cell using marimo's internal compiler and catches any SyntaxError exceptions that occur during the compilation process. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Cells with syntax errors cannot be executed, making the notebook non-functional. SyntaxErrors prevent marimo from creating the dependency graph and running the reactive execution system, breaking the core functionality of the notebook. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Invalid indentation [](#__codelineno-0-2)if True: [](#__codelineno-0-3)print("Hello") # Missing indentation` **Problematic:** `[](#__codelineno-1-1)# Invalid syntax [](#__codelineno-1-2)x = 1 + # Missing operand` **Problematic:** `[](#__codelineno-2-1)# Mismatched brackets [](#__codelineno-2-2)my_list = [1, 2, 3 # Missing closing bracket` **Solution:** `[](#__codelineno-3-1)# Fix indentation [](#__codelineno-3-2)if True: [](#__codelineno-3-3) print("Hello") # Proper indentation` **Solution:** `[](#__codelineno-4-1)# Complete expressions [](#__codelineno-4-2)x = 1 + 2 # Complete arithmetic expression` **Solution:** `[](#__codelineno-5-1)# Match brackets [](#__codelineno-5-2)my_list = [1, 2, 3] # Proper closing bracket` References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [Python SyntaxError Documentation](https://docs.python.org/3/tutorial/errors.html#syntax-errors) Self Import - marimo https://docs.marimo.io/guides/lint_rules/rules/self_import/ MR001: self-import[¶](#mr001-self-import "Permanent link") ---------------------------------------------------------- ⚠️ **Runtime** ❌ Not Fixable MR001: Importing a module with the same name as the file. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Analyzes import statements in each cell to detect cases where the imported module name matches the current file's name (without the .py extension). Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Importing a module with the same name as the file causes several issues: - Python may attempt to import the current file instead of the intended module - This can lead to circular import errors or unexpected behavior - It makes the code confusing and hard to debug - It can prevent the notebook from running correctly This is a runtime issue because it can cause import confusion and unexpected behavior. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic (in a file named `requests.py`):** `[](#__codelineno-0-1)import requests # Error: conflicts with file name` **Problematic (in a file named `math.py`):** `[](#__codelineno-1-1)from math import sqrt # Error: conflicts with file name` **Solution:** `[](#__codelineno-2-1)# Rename the file to something else, like my_requests.py [](#__codelineno-2-2)import requests # Now this works correctly` **Alternative Solution:** `[](#__codelineno-3-1)# Use a different approach that doesn't conflict [](#__codelineno-3-2)import urllib.request # Use alternative library` References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [Python Import System](https://docs.python.org/3/reference/import.html) General formatting - marimo https://docs.marimo.io/guides/lint_rules/rules/general_formatting/ ✨ **Formatting** 🛠️ Fixable MF001: General formatting issues with the notebook format. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Examines the notebook serialization for structural violations such as: - Missing or incorrect marimo import statements - Improperly formatted cell definitions - Missing app initialization code - Incorrect file generation metadata Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Format violations can prevent marimo from properly loading or executing notebooks. While these don't affect the Python code logic, formatting errors mark a deviation in the expected script structure, which can lead to unexpected behavior when run as a script, or when loading the notebook. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Missing marimo import [](#__codelineno-0-2)@app.cell [](#__codelineno-0-3)def __(): [](#__codelineno-0-4) return [](#__codelineno-0-5) [](#__codelineno-0-6)[](#__codelineno-0-7)if __name__ == "__main__": [](#__codelineno-0-8) app.run()` **Solution:** `[](#__codelineno-1-1)import marimo [](#__codelineno-1-2)[](#__codelineno-1-3)__generated_with = "0.1.0" [](#__codelineno-1-4)app = marimo.App() [](#__codelineno-1-5) [](#__codelineno-1-6)[](#__codelineno-1-7)@app.cell [](#__codelineno-1-8)def __(): [](#__codelineno-1-9) return [](#__codelineno-1-10) [](#__codelineno-1-11)[](#__codelineno-1-12)if __name__ == "__main__": [](#__codelineno-1-13) app.run()` **Note:** Most format issues are automatically fixable with `marimo check --fix`. References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [File Format Documentation](https://docs.marimo.io/guides/coming_from/jupyter/#marimo-file-format) Parse stdout - marimo https://docs.marimo.io/guides/lint_rules/rules/parse_stdout/ MF002: parse-stdout[¶](#mf002-parse-stdout "Permanent link") ------------------------------------------------------------ ✨ **Formatting** ❌ Not Fixable MF002: Parse captured stdout during notebook loading. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Captures and parses stdout output during notebook loading, looking for structured warning messages that include file and line number references. Creates diagnostics from any warnings or messages found. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ While stdout output doesn't prevent execution, it often indicates: - Deprecation warnings from imported libraries - Configuration issues - Potential compatibility problems - Code that produces unexpected side effects during import Examples[¶](#examples "Permanent link") --------------------------------------- **Captured stdout:** `[](#__codelineno-0-1)notebook.py:15: DeprecationWarning: 'imp' module is deprecated` **Result:** Creates a diagnostic pointing to line 15 with the deprecation warning. References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) Parse stderr - marimo https://docs.marimo.io/guides/lint_rules/rules/parse_stderr/ MF003: parse-stderr[¶](#mf003-parse-stderr "Permanent link") ------------------------------------------------------------ ✨ **Formatting** ❌ Not Fixable MF003: Parse captured stderr during notebook loading. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Captures stderr output during notebook loading and creates diagnostics from any error messages or warnings. This helps identify potential issues that don't prevent parsing but may affect runtime behavior. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Stderr output during parsing often indicates: - Syntax warnings (like invalid escape sequences) - Import warnings or errors - Deprecation notices from libraries - Configuration issues that might affect execution While these don't break the notebook, they can lead to unexpected behavior or indicate code that needs updating. Examples[¶](#examples "Permanent link") --------------------------------------- **Captured stderr:** `[](#__codelineno-0-1)notebook.py:68: SyntaxWarning: invalid escape sequence '\l'` **Result:** Creates a diagnostic pointing to line 68 about the invalid escape sequence. **Common issues:** - Raw strings needed: `r"\path\to\file"` instead of `"\path\to\file"` - Deprecated library usage - Missing import dependencies References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [Python Warning Categories](https://docs.python.org/3/library/warnings.html#warning-categories) Empty cells - marimo https://docs.marimo.io/guides/lint_rules/rules/empty_cells/ MF004: empty-cells[¶](#mf004-empty-cells "Permanent link") ---------------------------------------------------------- ✨ **Formatting** ⚠️ Unsafe Fixable MF004: Empty cells that can be safely removed. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Detects cells that contain only: - Whitespace characters (spaces, tabs, newlines) - Comments (lines starting with #) - Pass statements (`pass`) - Any combination of the above Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Empty cells can: - Create clutter in notebook structure - Add unnecessary complexity to the execution graph - Make notebooks harder to read and maintain - Increase file size without adding value While not functionally breaking, removing empty cells improves code clarity and reduces visual noise. Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)# Cell 1: Only whitespace` **Problematic:** `[](#__codelineno-1-1)# Cell 2: Only comments [](#__codelineno-1-2)# This is just a comment [](#__codelineno-1-3)# Nothing else here` **Problematic:** `[](#__codelineno-2-1)# Cell 3: Only pass statement [](#__codelineno-2-2)pass` **Problematic:** `[](#__codelineno-3-1)# Cell 4: Mix of comments, whitespace, and pass [](#__codelineno-3-2)# Some comment [](#__codelineno-3-3)[](#__codelineno-3-4)pass [](#__codelineno-3-5)# Another comment` **Note:** This fix requires `--unsafe-fixes` because removing cells changes the notebook structure, and potentially removes user-intended content. References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [Best Practices](https://docs.marimo.io/guides/best_practices/) Markdown Indentation - marimo https://docs.marimo.io/guides/lint_rules/rules/markdown_indentation/ ✨ **Formatting** 🛠️ Fixable MF007: Markdown strings in `mo.md()` should be properly indented. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Checks cells containing `mo.md()` calls to see if the markdown string content has unnecessary leading whitespace that should be removed. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Indented markdown strings: - Are harder to read when viewing the source code - Produce larger diffs when making changes - Don't match the standard marimo formatting style - Can be confusing when the indentation doesn't reflect the markdown structure Examples[¶](#examples "Permanent link") --------------------------------------- **Problematic:** `[](#__codelineno-0-1)mo.md( [](#__codelineno-0-2) r""" [](#__codelineno-0-3) # Title [](#__codelineno-0-4) [](#__codelineno-0-5) Some content here. [](#__codelineno-0-6) """ [](#__codelineno-0-7))` **Solution:** `[](#__codelineno-1-1)mo.md(r""" [](#__codelineno-1-2)# Title [](#__codelineno-1-3)[](#__codelineno-1-4)Some content here. [](#__codelineno-1-5)""")` **Note:** This fix is automatically applied with `marimo check --fix`. References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [Best Practices](https://docs.marimo.io/guides/best_practices/) SQL parse error - marimo https://docs.marimo.io/guides/lint_rules/rules/sql_parse_error/ ✨ **Formatting** ❌ Not Fixable MF005: SQL parsing errors during dependency analysis. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Captures SQL parsing error logs and creates diagnostics pointing to problematic SQL statements in cells. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ SQL parsing failures can lead to: - Incorrect dependency analysis for SQL-using cells - Missing dataframe references in dependency graph - Reduced effectiveness of reactive execution - Potential runtime errors when SQL is executed Examples[¶](#examples "Permanent link") --------------------------------------- **Triggered by:** - Invalid SQL syntax in cell code - Unsupported SQL dialects or extensions - Complex SQL that exceeds parser capabilities References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) * [SQL Support](https://docs.marimo.io/guides/sql/) Misc parse log - marimo https://docs.marimo.io/guides/lint_rules/rules/misc_log_capture/ MF006: misc-log-capture[¶](#mf006-misc-log-capture "Permanent link") -------------------------------------------------------------------- ✨ **Formatting** ❌ Not Fixable MF006: Miscellaneous log messages during processing. What it does[¶](#what-it-does "Permanent link") ----------------------------------------------- Captures warning and error level log messages that aren't handled by other specific log rules and creates diagnostics to surface them. Why is this bad?[¶](#why-is-this-bad "Permanent link") ------------------------------------------------------ Unhandled log messages may indicate: - Unexpected issues during notebook processing - Configuration problems - Library warnings that affect execution - Performance or resource issues Examples[¶](#examples "Permanent link") --------------------------------------- **Triggered by:** - General warnings from imported libraries - Configuration issues - Unexpected errors during processing References[¶](#references "Permanent link") ------------------------------------------- * [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/) SQL, dataframes, and plots - marimo https://docs.marimo.io/guides/working_with_data/ Working with data[¶](#working-with-data "Permanent link") --------------------------------------------------------- These guides introduce you to marimo's features for working with data, including SQL cells, no-code dataframe transformation tools, and plots whose selections are automatically sent back to Python. | Guide | Description | | --- | --- | | [SQL](https://docs.marimo.io/guides/working_with_data/sql/) | Use SQL to query dataframes, databases, CSVs, etc. | | [Dataframes](https://docs.marimo.io/guides/working_with_data/dataframes/) | Filter, search, and transform dataframes without code | | [Plotting](https://docs.marimo.io/guides/working_with_data/plotting/) | Send plot selections to Python | DataFrames - marimo https://docs.marimo.io/guides/working_with_data/dataframes/ Interactive dataframes[¶](#interactive-dataframes "Permanent link") ------------------------------------------------------------------- **marimo makes you more productive when working with dataframes**. * [Display dataframes](#displaying-dataframes) in a rich, interactive table and chart views * [Transform dataframes](#transforming-dataframes) with filters, groupbys, aggregations, and more, **no code required** * [Select data](#selecting-dataframes) from tables or charts and get selections back in Python as dataframes _marimo integrates with [Pandas](https://pandas.pydata.org/) and [Polars](https://pola.rs/) dataframes natively_. Displaying dataframes[¶](#displaying-dataframes "Permanent link") ----------------------------------------------------------------- marimo lets you page through, search, sort, and filter dataframes, making it extremely easy to get a feel for your data. marimo brings dataframes to life. Display dataframes by including them in the last expression of the cell, just like any other object. pandaspolarslive example `[](#__codelineno-0-1)import pandas as pd [](#__codelineno-0-2)[](#__codelineno-0-3)df = pd.read_json( [](#__codelineno-0-4) "https://raw.githubusercontent.com/vega/vega-datasets/master/data/cars.json" [](#__codelineno-0-5)) [](#__codelineno-0-6)df` `[](#__codelineno-1-1)import polars as pl [](#__codelineno-1-2)[](#__codelineno-1-3)df = pl.read_json( [](#__codelineno-1-4)"https://raw.githubusercontent.com/vega/vega-datasets/master/data/cars.json" [](#__codelineno-1-5)) [](#__codelineno-1-6)df` To opt out of the rich dataframe viewer, use [`mo.plain`](https://docs.marimo.io/api/layouts/plain/#marimo.plain " marimo.plain"): pandaspolarslive example `[](#__codelineno-3-1)import pandas as pd [](#__codelineno-3-2)import marimo as mo [](#__codelineno-3-3)[](#__codelineno-3-4)df = pd.read_json( [](#__codelineno-3-5)"https://raw.githubusercontent.com/vega/vega-datasets/master/data/cars.json" [](#__codelineno-3-6)) [](#__codelineno-3-7)mo.plain(df)` `[](#__codelineno-4-1)import polars as pl [](#__codelineno-4-2)import marimo as mo [](#__codelineno-4-3)[](#__codelineno-4-4)df = pl.read_json( [](#__codelineno-4-5)"https://raw.githubusercontent.com/vega/vega-datasets/master/data/cars.json" [](#__codelineno-4-6)) [](#__codelineno-4-7)mo.plain(df)` Transforming dataframes[¶](#transforming-dataframes "Permanent link") --------------------------------------------------------------------- ### No-code transformations[¶](#no-code-transformations "Permanent link") Use [`mo.ui.dataframe`](https://docs.marimo.io/api/inputs/dataframe/#marimo.ui.dataframe " marimo.ui.dataframe") to interactively transform a dataframe with a GUI, no coding required. When you're done, you can copy the code that the GUI generated for you and paste it into your notebook. Build transformations using a GUI The transformations you apply will turn into code which is accessible via the "code" tab. Copy the code of the transformation pandaspolarslive example `[](#__codelineno-6-1)# Cell 1 [](#__codelineno-6-2)import marimo as mo [](#__codelineno-6-3)import pandas as pd [](#__codelineno-6-4)[](#__codelineno-6-5)df = pd.DataFrame({"person": ["Alice", "Bob", "Charlie"], "age": [20, 30, 40]}) [](#__codelineno-6-6)transformed_df = mo.ui.dataframe(df) [](#__codelineno-6-7)transformed_df` `[](#__codelineno-7-1)# Cell 2 [](#__codelineno-7-2)# transformed_df.value holds the transformed dataframe [](#__codelineno-7-3)transformed_df.value` `[](#__codelineno-8-1)# Cell 1 [](#__codelineno-8-2)import marimo as mo [](#__codelineno-8-3)import polars as pl [](#__codelineno-8-4)[](#__codelineno-8-5)df = pl.DataFrame({"person": ["Alice", "Bob", "Charlie"], "age": [20, 30, 40]}) [](#__codelineno-8-6)transformed_df = mo.ui.dataframe(df) [](#__codelineno-8-7)transformed_df` `[](#__codelineno-9-1)# Cell 2 [](#__codelineno-9-2)# transformed_df.value holds the transformed dataframe [](#__codelineno-9-3)transformed_df.value` ### Custom filters[¶](#custom-filters "Permanent link") Create custom filters with marimo UI elements, like sliders and dropdowns. pandaspolarslive example `[](#__codelineno-11-1)# Cell 1 - create a dataframe [](#__codelineno-11-2)df = pd.DataFrame({"person": ["Alice", "Bob", "Charlie"], "age": [20, 30, 40]})` `[](#__codelineno-12-1)# Cell 2 - create a filter [](#__codelineno-12-2)age_filter = mo.ui.slider(start=0, stop=100, value=50, label="Max age") [](#__codelineno-12-3)age_filter` `[](#__codelineno-13-1)# Cell 3 - display the transformed dataframe [](#__codelineno-13-2)filtered_df = df[df["age"] < age_filter.value] [](#__codelineno-13-3)mo.ui.table(filtered_df)` `[](#__codelineno-14-1)# Cell 1 [](#__codelineno-14-2)import marimo as mo [](#__codelineno-14-3)import polars as pl [](#__codelineno-14-4)[](#__codelineno-14-5)df = pl.DataFrame({ [](#__codelineno-14-6) "name": ["Alice", "Bob", "Charlie", "David"], [](#__codelineno-14-7) "age": [25, 30, 35, 40], [](#__codelineno-14-8) "city": ["New York", "London", "Paris", "Tokyo"] [](#__codelineno-14-9)}) [](#__codelineno-14-10)[](#__codelineno-14-11)age_filter = mo.ui.slider.from_series(df["age"], label="Max age") [](#__codelineno-14-12)city_filter = mo.ui.dropdown.from_series(df["city"], label="City") [](#__codelineno-14-13)[](#__codelineno-14-14)mo.hstack([age_filter, city_filter])` `[](#__codelineno-15-1)# Cell 2 [](#__codelineno-15-2)filtered_df = df.filter((pl.col("age") <= age_filter.value) & (pl.col("city") == city_filter.value)) [](#__codelineno-15-3)mo.ui.table(filtered_df)` Select dataframe rows[¶](#selecting-dataframes "Permanent link") ---------------------------------------------------------------- Display dataframes as interactive, [selectable charts](https://docs.marimo.io/guides/working_with_data/plotting/) using [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") or [`mo.ui.plotly`](https://docs.marimo.io/api/plotting/#marimo.ui.plotly " marimo.ui.plotly"), or as a row-selectable table with [`mo.ui.table`](https://docs.marimo.io/api/inputs/table/#marimo.ui.table " marimo.ui.table"). Select points in the chart, or select a table row, and your selection is _automatically sent to Python as a subset of the original dataframe_. Select rows in a table, get them back as a dataframe pandaspolarslive example `[](#__codelineno-17-1)# Cell 1 - display a dataframe [](#__codelineno-17-2)import marimo as mo [](#__codelineno-17-3)import pandas as pd [](#__codelineno-17-4)[](#__codelineno-17-5)df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]}) [](#__codelineno-17-6)table = mo.ui.table(df, selection="multi") [](#__codelineno-17-7)table` `[](#__codelineno-18-1)# Cell 2 - display the selection [](#__codelineno-18-2)table.value` `[](#__codelineno-19-1)# Cell 1 - display a dataframe [](#__codelineno-19-2)import marimo as mo [](#__codelineno-19-3)import polars as pl [](#__codelineno-19-4)[](#__codelineno-19-5)df = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]}) [](#__codelineno-19-6)table = mo.ui.table(df, selection="multi") [](#__codelineno-19-7)table` `[](#__codelineno-20-1)# Cell 2 - display the selection [](#__codelineno-20-2)table.value` Dataframe panels[¶](#dataframe-panels "Permanent link") ------------------------------------------------------- Dataframe outputs in marimo come with several panels to help you visualize, explore, and page through your data interactively. These panels are accessible via toggles at the bottom-left of a dataframe output. If you need further control, after opening a panel you can * **pin the panel** to the side of your editor for persistent access; * **toggle focus** to automatically display the currently focused dataframe in the panel. Note Toggles are visible when editing notebooks (with `marimo edit ...`) but not when running notebooks as apps (with `marimo run ...`), except for the row viewer which is available in both. ### Row viewer panel[¶](#row-viewer-panel "Permanent link") To inspect individual rows, open the **row viewer**. This presents a vertical view of the selected row. * **Press `Space`** to select/deselect the current row * **Use arrow keys** (`←` `→`) to navigate between rows * **Click** on any row in the dataframe to view its data in the panel ### Column explorer panel[¶](#column-explorer-panel "Permanent link") To explore your data, open the **column explorer** where you can find summary statistics and charts for each column. Click the `+` button to add the chart code to a new cell. This requires the `altair` package to be installed. For large dataframes, `vegafusion` is also needed to render charts. To use the generated Python code, enable vegafusion in your notebook: `[](#__codelineno-22-1)import altair [](#__codelineno-22-2)[](#__codelineno-22-3)altair.data_transformers.enable("vegafusion")` ### Chart builder[¶](#chart-builder "Permanent link") The chart builder toggle lets you rapidly develop charts using a GUI, while also generating Python code to insert in your notebook. Refer to the [chart builder guide](https://docs.marimo.io/guides/working_with_data/plotting/#chart-builder) for more details. Preferences[¶](#preferences "Permanent link") --------------------------------------------- When you run a SQL cell in marimo, you can get the output returned as a dataframe. If you have a preference for a specific dataframe library as a default you can configure the "default SQL output" in the user settings by going to the "Runtime" tab. Configure the default SQL output Alternatively you can also use the [marimo configuration file](https://docs.marimo.io/guides/configuration/#user-configuration) to configure the default SQL output. `[](#__codelineno-23-1)[runtime] [](#__codelineno-23-2)default_sql_output = "native"` Example notebook[¶](#example-notebook "Permanent link") ------------------------------------------------------- For a comprehensive example of using Polars with marimo, check out our [Polars example notebook](https://github.com/marimo-team/marimo/blob/main/examples/third_party/polars/polars_example.py). Run it with: `[](#__codelineno-24-1)marimo edit https://raw.githubusercontent.com/marimo-team/marimo/main/examples/third_party/polars/polars_example.py` SQL - marimo https://docs.marimo.io/guides/working_with_data/sql/ Using SQL[¶](#using-sql "Permanent link") ----------------------------------------- marimo lets you mix and match **Python and SQL**: Use SQL to query Python dataframes (or databases like SQLite and Postgres), and get the query result back as a Python dataframe. To create a SQL cell, you first need to install additional dependencies, including [duckdb](https://duckdb.org/): install with pipinstall with uvinstall with conda `[](#__codelineno-0-1)pip install "marimo[sql]"` `[](#__codelineno-2-1)conda install -c conda-forge marimo duckdb polars` Example[¶](#example "Permanent link") ------------------------------------- In this example notebook, we have a Pandas dataframe and a SQL cell that queries it. Notice that the query result is returned as a Python dataframe and usable in subsequent cells. Creating SQL cells[¶](#creating-sql-cells "Permanent link") ----------------------------------------------------------- You can create SQL cells in one of three ways: 1. **Right-click** an "add cell" button ("+" icon) next to a cell and choose "SQL cell" 2. Convert a empty cell to SQL via the cell context menu 3. Click the SQL button that appears at the bottom of the notebook Add SQL Cell This creates a "**SQL**" cell for you, which is syntactic sugar for Python code. The underlying code looks like: `[](#__codelineno-3-1)output_df = mo.sql(f"SELECT * FROM my_table LIMIT {max_rows.value}")` Notice that we have an **`output_df`** variable in the cell. This contains the query result, and is a Polars DataFrame (if you have `polars` installed) or a Pandas DataFrame (if you don't). One of them must be installed in order to interact with the query result. The SQL statement itself is an f-string, letting you interpolate Python values into the query with `{}`. In particular, this means your SQL queries can depend on the values of UI elements or other Python values, and they are fit into marimo's reactive dataflow graph. SQL Output Types[¶](#sql-output-types "Permanent link") ------------------------------------------------------- marimo supports different output types for SQL queries, which is particularly useful when working with large datasets. You can configure this in your application configuration in the top right of the marimo editor. The available options are: * `native`: Uses DuckDB's native lazy relation (recommended for best performance) * `lazy-polars`: Returns a lazy Polars DataFrame * `pandas`: Returns a Pandas DataFrame * `polars`: Returns an eager Polars DataFrame * `auto`: Automatically chooses based on installed packages (first tries `polars` then `pandas`) For best performance with large datasets, we recommend using `native` to avoid loading the entire result set into memory and to more easily chain SQL cells together. By default, only the first 10 rows are displayed in the UI to prevent memory issues. Set a default The default output type is currently `auto`, but we recommend explicitly setting the output type to `native` for best performance with large datasets or `polars` if you need to work with the results in Python code. You can configure this in your application settings. Reference a local dataframe[¶](#reference-a-local-dataframe "Permanent link") ----------------------------------------------------------------------------- You can reference a local dataframe in your SQL cell by using the name of the Python variable that holds the dataframe. If you have a database connection with a table of the same name, the database table will be used instead. Reference a dataframe Since the output dataframe variable (`_df`) has an underscore, making it private, it is not referenceable from other cells. Reference the output of a SQL cell[¶](#reference-the-output-of-a-sql-cell "Permanent link") ------------------------------------------------------------------------------------------- Defining a non-private (non-underscored) output variable in the SQL cell allows you to reference the resulting dataframe in other Python and SQL cells. Reference the SQL result Querying files, databases, and APIs[¶](#querying-files-databases-and-apis "Permanent link") ------------------------------------------------------------------------------------------- In the above example, you may have noticed we queried an HTTP endpoint instead of a local dataframe. We are not only limited to querying local dataframes; we can also query files, databases such as Postgres and SQLite, and APIs: `[](#__codelineno-4-1)-- or [](#__codelineno-4-2)SELECT * FROM 's3://my-bucket/file.parquet'; [](#__codelineno-4-3)-- or [](#__codelineno-4-4)SELECT * FROM read_csv('path/to/example.csv'); [](#__codelineno-4-5)-- or [](#__codelineno-4-6)SELECT * FROM read_parquet('path/to/example.parquet');` For a full list you can check out the [duckdb extensions](https://duckdb.org/docs/extensions/overview). You can also check out our [examples on GitHub](https://github.com/marimo-team/marimo/tree/main/examples/sql). Escaping SQL brackets[¶](#escaping-sql-brackets "Permanent link") ----------------------------------------------------------------- Our "SQL" cells are really just Python under the hood to keep notebooks as pure Python scripts. By default, we use `f-strings` for SQL strings, which allows for parameterized SQL like `SELECT * from table where value < {min}`. To escape real `{`/`}` that you don't want parameterized, use double `{{...}}`: `[](#__codelineno-5-1)SELECT unnest([{{'a': 42, 'b': 84}}, {{'a': 100, 'b': NULL}}]);` Connecting to a custom database[¶](#connecting-to-a-custom-database "Permanent link") ------------------------------------------------------------------------------------- There are two ways to connect to a database in marimo: ### 1\. Using the UI[¶](#1-using-the-ui "Permanent link") Click the "Add Database Connection" button in your notebook to connect to PostgreSQL, MySQL, SQLite, DuckDB, Snowflake, or BigQuery databases. The UI will guide you through entering your connection details securely. Environment variables picked up from your [`dotenv`](https://docs.marimo.io/guides/configuration/runtime_configuration/#environment-variables) can be used to fill out the database configuration fields. Add a database connection through the UI If you'd like to connect to a database that isn't supported by the UI, you can use the code method below, or submit a [feature request](https://github.com/marimo-team/marimo/issues/new?title=New%20database%20connection:&labels=enhancement&template=feature_request.yaml). ### 2\. Using Code[¶](#2-using-code "Permanent link") You can bring your own database via a **connection engine** with one of the following libraries * [SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/connections.html#basic-usage) * [SQLModel](https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/?h=create+engine#create-the-engine) * [Ibis](https://ibis-project.org/backends/athena) * [Custom DuckDB connection](https://duckdb.org/docs/api/python/overview.html#connection-options) * [ClickHouse Connect](https://clickhouse.com/docs/integrations/python#introduction) * [chDB](https://clickhouse.com/docs/chdb) By default, marimo uses the [in-memory duckdb connection](https://duckdb.org/docs/connect/overview.html#in-memory-database). List of supported databases Updated: 2025-04-30. This list is not exhaustive. | Database | Library | | --- | --- | | Amazon Athena | `sqlalchemy`, `sqlmodel`, `ibis` | | Amazon Redshift | `sqlalchemy`, `sqlmodel` | | Apache Drill | `sqlalchemy`, `sqlmodel` | | Apache Druid | `sqlalchemy`, `sqlmodel`, `ibis` | | Apache Hive and Presto | `sqlalchemy`, `sqlmodel` | | Apache Solr | `sqlalchemy`, `sqlmodel` | | BigQuery | `sqlalchemy`, `sqlmodel`, `ibis` | | ClickHouse | `clickhouse_connect`, `chdb` | | CockroachDB | `sqlalchemy`, `sqlmodel` | | Databricks | `sqlalchemy`, `sqlmodel`, `ibis` | | dlt | `ibis` | | Datafusion | `ibis` | | DuckDB | `duckdb` | | EXASolution | `sqlalchemy`, `sqlmodel`, `ibis` | | Elasticsearch (readonly) | `sqlalchemy`, `sqlmodel` | | Firebolt | `sqlalchemy`, `sqlmodel` | | Flink | `ibis` | | Google Sheets | `sqlalchemy`, `sqlmodel` | | Impala | `sqlalchemy`, `sqlmodel`, `ibis` | | Microsoft Access | `sqlalchemy`, `sqlmodel` | | Microsoft SQL Server | `sqlalchemy`, `sqlmodel`, `ibis` | | MonetDB | `sqlalchemy`, `sqlmodel` | | MySQL | `sqlalchemy`, `sqlmodel`, `ibis` | | OpenGauss | `sqlalchemy`, `sqlmodel` | | Oracle | `sqlalchemy`, `sqlmodel`, `ibis` | | PostgreSQL | `sqlalchemy`, `sqlmodel`, `ibis` | | PySpark | `ibis` | | RisingWave | `ibis` | | SAP HANA | `sqlalchemy`, `sqlmodel` | | Snowflake | `sqlalchemy`, `sqlmodel`, `ibis` | | SQLite | `sqlalchemy`, `sqlmodel`, `ibis` | | Teradata Vantage | `sqlalchemy`, `sqlmodel` | | TimePlus | `sqlalchemy`, `sqlmodel` | | Trino | `sqlalchemy`, `sqlmodel`, `ibis` | Define the engine as a Python variable in a cell: SQLAlchemySQLModelIbisDuckDBClickHouse ConnectchDB `[](#__codelineno-6-1)import sqlalchemy [](#__codelineno-6-2)[](#__codelineno-6-3)# Create an in-memory SQLite database with SQLAlchemy [](#__codelineno-6-4)sqlite_engine = sqlachemy.create_engine("sqlite:///:memory:")` `[](#__codelineno-7-1)import sqlmodel [](#__codelineno-7-2)[](#__codelineno-7-3)# Create an in-memory SQLite database with SQLModel [](#__codelineno-7-4)sqlite_engine = sqlmodel.create_engine("sqlite:///:memory:")` `[](#__codelineno-8-1)import ibis [](#__codelineno-8-2)[](#__codelineno-8-3)# Create an in-memory SQLite database with Ibis [](#__codelineno-8-4)sqlite_engine = ibis.connect("sqlite:///:memory:")` `[](#__codelineno-9-1)import duckdb [](#__codelineno-9-2)[](#__codelineno-9-3)# Create a DuckDB connection [](#__codelineno-9-4)duckdb_conn = duckdb.connect("file.db")` ClickHouse Connect enables remote connections to ClickHouse databases. Refer to [the official docs](https://clickhouse.com/docs/integrations/python#gather-your-connection-details) for more configuration options. `[](#__codelineno-10-1)import clickhouse_connect [](#__codelineno-10-2)[](#__codelineno-10-3)engine = clickhouse_connect.get_client(host="localhost", port=8123, username="default", password="password")` Warning chDB is still new. You may experience issues with your queries. We recommend only using one connection at a time. Refer to [chDB docs](https://github.com/orgs/chdb-io/discussions/295) for more information. `[](#__codelineno-11-1)import chdb [](#__codelineno-11-2)[](#__codelineno-11-3)connection = chdb.connect(":memory:") [](#__codelineno-11-4)[](#__codelineno-11-5)# Supported formats with examples: [](#__codelineno-11-6)":memory:" # In-memory database [](#__codelineno-11-7)"test.db" # Relative path [](#__codelineno-11-8)"file:test.db" # Explicit file protocol [](#__codelineno-11-9)"/path/to/test.db" # Absolute path [](#__codelineno-11-10)"file:/path/to/test.db" # Absolute path with protocol [](#__codelineno-11-11)"file:test.db?param1=value1¶m2=value2" # With query parameters [](#__codelineno-11-12)"file::memory:?verbose&log-level=test" # In-memory with parameters [](#__codelineno-11-13)"///path/to/test.db?param1=value1" # Triple slash absolute path` marimo will auto-discover the engine and let you select it in the SQL cell's connection dropdown. Choose a custom database connection Database, schema, and table auto-discovery[¶](#database-schema-and-table-auto-discovery "Permanent link") --------------------------------------------------------------------------------------------------------- marimo will automatically discover the database connection and display the database, schemas, tables, and columns in the Data Sources panel. This panels lets you quickly navigate your database schema and reference tables and columns to pull in your SQL queries. Data Sources panel Note By default, marimo auto-discovers databases and schemas, but not tables and columns (to avoid performance issues with large databases). You can configure this behavior in your `pyproject.toml` file. Options are `true`, `false`, or `"auto"`. `"auto"` will determine whether to auto-discover based on the type of database (e.g. when the value is `"auto"`, Snowflake and BigQuery will not auto-discover tables and columns while SQLite, Postgres, and MySQL will): pyproject.toml `[](#__codelineno-12-1)[tool.marimo.datasources] [](#__codelineno-12-2)auto_discover_schemas = true # Default: true [](#__codelineno-12-3)auto_discover_tables = "auto" # Default: "auto" [](#__codelineno-12-4)auto_discover_columns = "auto" # Default: false` Catalogs[¶](#catalogs "Permanent link") --------------------------------------- marimo supports connecting to Iceberg catalogs. You can click the "+" button in the Datasources panel or manually create a [PyIceberg](https://py.iceberg.apache.org/) `Catalog` connection. PyIceberg supports a variety of catalog implementations including REST, SQL, Glue, DynamoDB, and more. `[](#__codelineno-13-1)from pyiceberg.catalog.rest import RestCatalog [](#__codelineno-13-2)[](#__codelineno-13-3)catalog = RestCatalog( [](#__codelineno-13-4) name="catalog", [](#__codelineno-13-5) warehouse="1234567890", [](#__codelineno-13-6) uri="https://my-catalog.com", [](#__codelineno-13-7) token="my-token", [](#__codelineno-13-8))` Catalogs will appear in the Datasources panel, but they cannot be used as an engine in SQL cells. However, you can still load the table and use it in subsequent Python or SQL cells. `[](#__codelineno-14-1)df = catalog.load_table(("my-namespace", "my-table")).to_polars()` Utilities[¶](#utilities "Permanent link") ----------------------------------------- marimo provides a few utilities when working with SQL **SQL Linter** Lint your SQL code and provide better autocompletions and error highlighting. To disable the linter, you can set the `sql_linter` configuration to `false` in your `pyproject.toml` file or disable it in the marimo editor's settings menu. **SQL Formatting** Click on the paint roller icon at the bottom right of the SQL cell to format your SQL code. **SQL Mode** For In-Memory DuckDB, marimo offers a Validate mode that will validate your SQL as you write it. Under the hood, this runs a debounced query in EXPLAIN mode and returns the parsed errors. Interactive tutorial[¶](#interactive-tutorial "Permanent link") --------------------------------------------------------------- For an interactive tutorial, run at your command-line. Examples[¶](#examples "Permanent link") --------------------------------------- Check out our [examples on GitHub](https://github.com/marimo-team/marimo/tree/main/examples/sql). Plotting - marimo https://docs.marimo.io/guides/working_with_data/plotting/ marimo supports most major plotting libraries, including Matplotlib, Seaborn, Plotly, Altair, and HoloViews. Just import your plotting library of choice and use it as you normally would. For Altair and Plotly plots, marimo does something special: use [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") or [`mo.ui.plotly`](https://docs.marimo.io/api/plotting/#marimo.ui.plotly " marimo.ui.plotly") to connect frontend selections to Python! Reactive plots! marimo supports reactive plots via [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") and [`mo.ui.plotly`](https://docs.marimo.io/api/plotting/#marimo.ui.plotly " marimo.ui.plotly")! Select and filter with your mouse, and marimo _automatically makes the selected data available in Python as a Pandas dataframe_! Reactive plots! ⚡[¶](#reactive-plots "Permanent link") ------------------------------------------------------ Requirements Reactive plots currently require Altair or Plotly. Install with `pip install altair` or `pip install plotly`, depending on which library you are using. Selections in plotly are limited to scatter plots, treemaps charts, and sunbursts charts, while Altair supports a larger class of plots for selections. ### Altair[¶](#altair "Permanent link") Use [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") to easily create interactive, selectable plots: _selections you make on the frontend are automatically made available as Pandas dataframes in Python._ Wrap an Altair chart in [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") to make it **reactive**: select data on the frontend, access it via the chart's `value` attribute (`chart.value`). #### Disabling automatic selection[¶](#disabling-automatic-selection "Permanent link") marimo automatically adds a default selection based on the mark type, however, you may want to customize the selection behavior of your Altair chart. You can do this by setting `chart_selection` and `legend_selection` to `False`, and using `.add_params` directly on your Altair chart. `[](#__codelineno-1-1)# Create an interval selection [](#__codelineno-1-2)brush = alt.selection_interval(encodings=["x"]) [](#__codelineno-1-3)[](#__codelineno-1-4)_chart = ( [](#__codelineno-1-5) alt.Chart(traces, height=150) [](#__codelineno-1-6) .mark_line() [](#__codelineno-1-7) .encode(x="index:Q", y="value:Q", color="traces:N") [](#__codelineno-1-8) .add_params(brush) # add the selection to the chart [](#__codelineno-1-9)) [](#__codelineno-1-10)[](#__codelineno-1-11)chart = mo.ui.altair_chart( [](#__codelineno-1-12) _chart, [](#__codelineno-1-13) # disable automatic selection [](#__codelineno-1-14) chart_selection=False, [](#__codelineno-1-15) legend_selection=False [](#__codelineno-1-16)) [](#__codelineno-1-17)chart # You can now access chart.value to get the selected data` _Reactive plots are just one way that marimo **makes your data tangible**._ #### Example[¶](#example "Permanent link") `[](#__codelineno-2-1)import marimo as mo [](#__codelineno-2-2)import altair as alt [](#__codelineno-2-3)import vega_datasets [](#__codelineno-2-4)[](#__codelineno-2-5)# Load some data [](#__codelineno-2-6)cars = vega_datasets.data.cars() [](#__codelineno-2-7)[](#__codelineno-2-8)# Create an Altair chart [](#__codelineno-2-9)chart = alt.Chart(cars).mark_point().encode( [](#__codelineno-2-10) x='Horsepower', # Encoding along the x-axis [](#__codelineno-2-11) y='Miles_per_Gallon', # Encoding along the y-axis [](#__codelineno-2-12) color='Origin', # Category encoding by color [](#__codelineno-2-13)) [](#__codelineno-2-14)[](#__codelineno-2-15)# Make it reactive ⚡ [](#__codelineno-2-16)chart = mo.ui.altair_chart(chart)` `[](#__codelineno-3-1)# In a new cell, display the chart and its data filtered by the selection [](#__codelineno-3-2)mo.vstack([chart, chart.value.head()])` #### Learning Altair[¶](#learning-altair "Permanent link") If you're new to **Altair**, we highly recommend exploring the [Altair documentation](https://altair-viz.github.io/). Altair provides a declarative, concise, and simple way to create highly interactive and sophisticated plots. Altair is based on [Vega-Lite](https://vega.github.io/vega-lite/), an exceptional tool for creating interactive charts that serves as the backbone for marimo's reactive charting capabilities. ##### Concepts[¶](#concepts "Permanent link") Learn by doing? Skip this section! This section summarizes the main concepts used by Altair (and Vega-Lite). Feel free to skip this section and return later. Our choice to use the Vega-Lite specification was driven by its robust data model, which is well-suited for data analysis. Some key concepts are summarized below. (For a more detailed explanation, with examples, we recommend the [Basic Statistical Visualization](https://altair-viz.github.io/getting_started/starting.html) tutorial from Altair.) * **Data Source**: This is the information that will be visualized in the chart. It can be provided in various formats such as a dataframe, a list of dictionaries, or a URL pointing to the data source. * **Mark Type**: This refers to the visual representation used for each data point on the chart. The options include 'bar', 'dot', 'circle', 'area', and 'line'. Each mark type offers a different way to visualize and interpret the data. * **Encoding**: This is the process of mapping various aspects or dimensions of the data to visual characteristics of the marks. Encodings can be of different types: * **Positional Encodings**: These are encodings like 'x' and 'y' that determine the position of the marks in the chart. * **Categorical Encodings**: These are encodings like 'color' and 'shape' that categorize data points. They are typically represented in a legend for easy reference. * **Transformations**: These are operations that can be applied to the data before it is visualized, for example, filtering and aggregation. These transformations allow for more complex and nuanced visualizations. **Automatically interactive.** marimo adds interactivity automatically, based on the mark used and the encodings. For example, if you use a `mark_point` and an `x` encoding, marimo will automatically add a brush selection to the chart. If you add a `color` encoding, marimo will add a legend and a click selection. #### Automatic Selections[¶](#automatic-selections "Permanent link") By default [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") will make the chart and legend selectable. Depending on the mark type, the chart will either have a `point` or `interval` ("brush") selection. When using non-positional encodings (color, size, etc), [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") will also make the legend selectable. Selection configurable through `*_selection` params in [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart"). See the [API docs](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart") for details. Note You may still add your own selection parameters via Altair or Vega-Lite. marimo will not override your selections. #### Altair transformations[¶](#altair-transformations "Permanent link") Altair supports a variety of transformations, such as filtering, aggregation, and sorting. These transformations can be used to create more complex and nuanced visualizations. For example, you can use a filter to show only the points that meet a certain condition, or use an aggregation to show the average value of a variable. In order for marimo's reactive plots to work with transformations, you must install `vegafusion`, as this feature uses `chart.transformed_data` (which requires version 1.4.0 or greater of the `vegafusion` packages). `[](#__codelineno-4-1)# These can be installed with pip using: [](#__codelineno-4-2)pip install "vegafusion[embed]>=1.4.0" [](#__codelineno-4-3)# Or with conda using: [](#__codelineno-4-4)conda install -c conda-forge "vegafusion-python-embed>=1.4.0" "vegafusion>=1.4.0"` ### Plotly[¶](#plotly "Permanent link") mo.ui.plotly only supports scatter plots, treemaps charts, and sunbursts charts marimo can render any Plotly plot, but [`mo.ui.plotly`](https://docs.marimo.io/api/plotting/#marimo.ui.plotly " marimo.ui.plotly") only supports reactive selections for scatter plots, treemaps charts, and sunbursts charts. If you require other kinds of selection, consider using [`mo.ui.altair_chart`](https://docs.marimo.io/api/plotting/#marimo.ui.altair_chart " marimo.ui.altair_chart"). Use [`mo.ui.plotly`](https://docs.marimo.io/api/plotting/#marimo.ui.plotly " marimo.ui.plotly") to create selectable Plotly plots whose values are sent back to Python on selection. matplotlib[¶](#matplotlib "Permanent link") ------------------------------------------- To output a matplotlib plot in a cell's output area, include its `Axes` or `Figure` object as the last expression in your notebook. For example: ``[](#__codelineno-6-1)plt.plot([1, 2]) [](#__codelineno-6-2)# plt.gca() gets the current `Axes` [](#__codelineno-6-3)plt.gca()`` or `[](#__codelineno-7-1)fig, ax = plt.subplots() [](#__codelineno-7-2)[](#__codelineno-7-3)ax.plot([1, 2]) [](#__codelineno-7-4)ax` If you want to output the plot in the console area, use `plt.show()` or `fig.show()`. ### Interactive plots[¶](#interactive-plots "Permanent link") To make matplotlib plots interactive, use [mo.mpl.interactive](https://docs.marimo.io/api/plotting/#marimo.mpl.interactive " marimo.mpl.interactive"). (Matplotlib plots are not yet reactive.) Chart builder[¶](#chart-builder "Permanent link") ------------------------------------------------- marimo comes with a built-in chart builder that makes it easy to create plots specialized to your dataframes with just a few clicks. As you make your charts, marimo generates Python code that you can add to your notebook to save them. You can toggle the chart builder with a button at the bottom-left of a dataframe output. This provides a GUI interface to create many kinds of plots, while also generating Python code. Charts are powered by [Vega-Lite](https://vega.github.io/vega-lite/). To save a chart, click the `+` button in the `Python code` tab to add the code to a new cell. Note This feature is in active development. Please report any issues or feedback [here](https://github.com/marimo-team/marimo/issues). Package management - marimo https://docs.marimo.io/guides/package_management/ The following guides cover how to import, install, and otherwise manage the Python dependencies of your notebooks. | Guide | Description | | --- | --- | | [Importing packages](https://docs.marimo.io/guides/package_management/importing_packages/) | How marimo finds packages on import | | [Installing packages](https://docs.marimo.io/guides/package_management/installing_packages/) | Installing packages with marimo's UI | | [Inlining dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/) | Create self-contained notebooks by inlining dependencies in notebook files | | [Notebooks in existing projects](https://docs.marimo.io/guides/package_management/notebooks_in_projects/) | Working with marimo notebooks in existing Python projects | | [Using uv](https://docs.marimo.io/guides/package_management/using_uv/) | A guide to using the uv package manager with marimo | Installing packages - marimo https://docs.marimo.io/guides/package_management/installing_packages/ marimo supports package management for `pip`, `uv`, `poetry`, `pixi`, and `rye`. When marimo comes across a module that is not installed, you will be prompted to install it using your preferred package manager. Once the module is installed, all cells that depend on the module will be rerun (or marked as stale). You can also install (and remove) packages using the package manager sidebar panel. Resolving package names We use a heuristic for guessing the package name in your registry (e.g. PyPI) from the module name. It is possible that the package name is different from the module name. If you encounter an error, please [file an issue](https://github.com/marimo-team/marimo/issues) or help us by adding your mapping [directly to the codebase](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/module_name_to_pypi_name.py). **Notes.** * When using imperative style package managers like `pip`, packages are installed directly in the active virtual environment. * When using `uv`, marimo will decide whether to add it to your `pyproject.toml` (if running as part of a uv project), or whether to install it imperatively with `uv pip` (otherwise). * When running in a [package sandbox](https://docs.marimo.io/guides/package_management/inlining_dependencies/), package installation and removal also updates the notebook's inline dependencies. Importing packages - marimo https://docs.marimo.io/guides/package_management/importing_packages/ By default, marimo searches for packages in the [virtual environment](https://docs.python.org/3/tutorial/venv.html) it was started in. For example, if you run `[](#__codelineno-0-1)source /path/to/venv/bin/activate [](#__codelineno-0-2)marimo edit my_notebook.py` you'll be able to import packages installed in the environment you just activated. You'll also be able to install packages into this environment using the marimo editor's [package management UI](https://docs.marimo.io/guides/package_management/installing_packages/). Using uv? See our [uv guide](https://docs.marimo.io/guides/package_management/using_uv/) for details on how to use marimo as part of uv projects or as self-contained scripts. Inlining dependencies[¶](#inlining-dependencies "Permanent link") ----------------------------------------------------------------- As an alternative to manually creating and managing a virtual environment, you can let marimo manage virtual environments for you, on a per-notebook basis. If you create a notebook with the `--sandbox` flag — `[](#__codelineno-1-1)marimo edit --sandbox my_notebook.py` — marimo will start your notebook in an isolated environment and keep track of the dependencies you install from the editor. These dependencies are inlined in the notebook file, so that the next time you run the notebook, marimo will run it in an isolated environment with just those dependencies. See our guide on [inlining dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/) to learn more. What about kernels? Unlike Jupyter, marimo does not have a concept of "kernels"; notebooks simply use the active virtual environment. The main feature of kernels is to allow different notebooks to depend on different packages, even within the same project. marimo's package sandbox provides this functionality, while also being far simpler to use than custom kernels. Importing local modules[¶](#importing-local-modules "Permanent link") --------------------------------------------------------------------- marimo resolves imports just as Python does: by searching for packages in the directories listed in `sys.path`. That means that in addition to the virtual environment, marimo will search for modules in the directory in which the notebook lives. For example, when you run `[](#__codelineno-2-1)marimo edit /path/to/notebook_dir/notebook.py` marimo will look for modules in `/path/to/notebook_dir`. However, this means that you may need to take additional steps to import modules that live outside this directory. What steps you take depends on whether your code is organized as a Python package. Remember: notebooks are just Python programs In the examples below, notebooks are stored in a separate notebooks directory, which is traditional. However, since marimo notebooks are just Python modules, you can just as well include them in your `src/` directory alongside other Python modules. ### From non-package projects[¶](#from-non-package-projects "Permanent link") You can configure the Python path to accommodate directory structures that look like this: `[](#__codelineno-3-1). [](#__codelineno-3-2)├── notebooks [](#__codelineno-3-3)│   └── my_notebook.py [](#__codelineno-3-4)├── pyproject.toml [](#__codelineno-3-5)└── src [](#__codelineno-3-6) └── my_module.py` In particular, to make `import my_module` work when running editrunscript `[](#__codelineno-4-1)marimo edit notebooks/my_notebook.py` `[](#__codelineno-5-1)marimo run notebooks/my_notebook.py` `[](#__codelineno-6-1)python notebooks/my_notebook.py` add the following configuration to your `pyproject.toml`: pyproject.toml `[](#__codelineno-7-1)[tool.marimo.runtime] [](#__codelineno-7-2)pythonpath = ["src"]` ### From packages[¶](#from-packages "Permanent link") New to Python packages? A [Python package](https://docs.python.org/3/tutorial/modules.html#packages) is a way of structuring Python source files so that the collection of files can be installed in an environment, imported using "dot" notation like `from my_package.my_module import my_function`, and optionally uploaded to package registries like PyPI. If you are new to packages, and find you need to create one, we recommend using [uv](https://docs.astral.sh/uv/) (`uv init --package`). A package has a directory structure like this: `[](#__codelineno-8-1). [](#__codelineno-8-2)├── notebooks [](#__codelineno-8-3)│   └── my_notebook.py [](#__codelineno-8-4)├── pyproject.toml [](#__codelineno-8-5)└── src [](#__codelineno-8-6) └── my_package [](#__codelineno-8-7) ├── __init__.py [](#__codelineno-8-8) └── my_module.py` Say `my_notebook` has a cell with `[](#__codelineno-9-1)from my_package import my_module` Provided that editrunscript `[](#__codelineno-10-1)marimo edit notebooks/my_notebook.py` `[](#__codelineno-11-1)marimo run notebooks/my_notebook.py` `[](#__codelineno-12-1)python notebooks/my_notebook.py` is run from an environment in which your package is installed, marimo will import `my_module` without issue. For example, if you are using `uv`, simply run `[](#__codelineno-13-1)uv run --with marimo marimo edit notebooks/my_notebook.py` Inlining dependencies - marimo https://docs.marimo.io/guides/package_management/inlining_dependencies/ marimo is the only Python notebook that is reproducible down to the packages, letting you inline Python dependencies in notebook files and running notebooks in isolated or "sandboxed" venvs. This lets you share standalone notebooks without shipping `requirements.txt` files alongside them, and guarantees your notebooks will work weeks, months, even years into the future. To opt-in to dependency inlining, use the `sandbox` flag: editrunnew `[](#__codelineno-0-1)marimo edit --sandbox notebook.py` `[](#__codelineno-1-1)marimo run --sandbox notebook.py` When running with `--sandbox`, marimo: 1. tracks the packages and versions used by your notebook, saving them in the notebook file; 2. runs in an isolated virtual environment ("sandbox") that only contains the notebook dependencies. marimo's sandbox provides two key benefits. (1) Notebooks that carry their own dependencies are easy to share — just send the `.py` file. (2) Isolating a notebook from other installed packages prevents obscure bugs. You can also run sandboxed notebooks as scripts: Solving the notebook reproducibility crisis marimo's support for package sandboxing is only possible because marimo notebooks are stored as pure Python files, letting marimo take advantage of new Python standards like [PEP 723](https://peps.python.org/pep-0723/) and tools like uv. In contrast, traditional notebooks like Jupyter are stored as JSON files, and which suffer from a [reproducibility crisis](https://leomurta.github.io/papers/pimentel2019a.pdf) due to the lack of package management. When running with `--sandbox`, marimo automatically tracks package metadata in your notebook file using inline script metadata, which per [PEP 723](https://peps.python.org/pep-0723/) is essentially a pyproject.toml inlined as the script's header. This metadata is used to manage the notebook's dependencies and Python version, and looks something like this: `[](#__codelineno-4-1)# /// script [](#__codelineno-4-2)# requires-python = ">=3.11" [](#__codelineno-4-3)# dependencies = [ [](#__codelineno-4-4)# "pandas==", [](#__codelineno-4-5)# "altair==", [](#__codelineno-4-6)# ] [](#__codelineno-4-7)# ///` Example notebooks The [example notebooks](https://github.com/marimo-team/marimo/tree/main/examples) in our GitHub repo were all created using `--sandbox`. Take a look at any of them for an example of the full script metadata. ### Adding and removing packages[¶](#adding-and-removing-packages "Permanent link") **Using the marimo editor.** When you import a module in the marimo editor, if marimo detects that it is a third-party package, it will automatically be added to the script metadata. Removing an import does _not_ remove it from the script metadata (since library code may still use the package). Adding packages via the package manager panel will also add packages to script metadata, and removing packages from the panel will in turn remove them from the script metadata. **Adding packages manually.** You can manually manage your notebook's requirements: * edit the script metadata manually in an editor like VS Code or neovim. * use `uv` from the command-line: `[](#__codelineno-5-1)uv add --script notebook.py numpy` `[](#__codelineno-6-1)uv remove --script notebook.py numpy` ### Package locations[¶](#package-locations "Permanent link") By default, marimo will look for packages on PyPI. You can edit the script metadata to look for packages elsewhere, such as on GitHub. Consult the [Python packaging documentation](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#examples) for more information. ### Local development with editable installs[¶](#local-development-with-editable-installs "Permanent link") When developing a local package, you can install it in editable mode using the `[tool.uv.sources]` section in the script metadata. For example: `[](#__codelineno-7-1)# /// script [](#__codelineno-7-2)# requires-python = ">=3.11" [](#__codelineno-7-3)# dependencies = [ [](#__codelineno-7-4)# "my-package", [](#__codelineno-7-5)# ] [](#__codelineno-7-6)# [](#__codelineno-7-7)# [tool.uv.sources] [](#__codelineno-7-8)# my-package = { path = "../", editable = true } [](#__codelineno-7-9)# ///` This is particularly useful when you want to test changes to your package without reinstalling it. The package will be installed in "editable" mode, meaning changes to the source code will be reflected immediately in your notebook. ### Specifying alternative package indexes[¶](#specifying-alternative-package-indexes "Permanent link") When you need to use packages from a custom PyPI server or alternative index, you can specify these in your script metadata using the `[[tool.uv.index]]` section. This is useful for private packages or when you want to use packages from a specific source. `[](#__codelineno-8-1)# /// script [](#__codelineno-8-2)# requires-python = ">=3.11" [](#__codelineno-8-3)# dependencies = [ [](#__codelineno-8-4)# "pandas==", [](#__codelineno-8-5)# "private-package==", [](#__codelineno-8-6)# ] [](#__codelineno-8-7)# [](#__codelineno-8-8)# [[tool.uv.index]] [](#__codelineno-8-9)# name = "custom-index" [](#__codelineno-8-10)# url = "https://custom-pypi-server.example.com/simple/" [](#__codelineno-8-11)# explicit = true [](#__codelineno-8-12)# [](#__codelineno-8-13)# [tool.uv.sources] [](#__codelineno-8-14)# private-package = { index = "custom-index" } [](#__codelineno-8-15)# ///` In this example: * `[[tool.uv.index]]` defines a custom package index * `name` is an identifier for the index * `url` points to your custom PyPI server * `explicit = true` means this index will only be used for packages explicitly associated with it * `[tool.uv.sources]` specifies which packages should come from which indexes This approach ensures that specific packages are always fetched from your designated custom index, while other packages continue to be fetched from the default PyPI repository. Configuration[¶](#configuration "Permanent link") ------------------------------------------------- Running marimo in a sandbox environment uses `uv` to create an isolated virtual environment. You can use any of `uv`'s [supported environment variables](https://docs.astral.sh/uv/configuration/environment/). ### Choosing the Python version[¶](#choosing-the-python-version "Permanent link") For example, you can specify the Python version using the `UV_PYTHON` environment variable: `[](#__codelineno-9-1)UV_PYTHON=3.13 marimo edit --sandbox notebook.py` ### Other common configuration[¶](#other-common-configuration "Permanent link") Another common configuration is `uv`'s link mode: `[](#__codelineno-10-1)UV_LINK_MODE="copy" marimo edit --sandbox notebook.py` Sharing on the web[¶](#sharing-on-the-web "Permanent link") ----------------------------------------------------------- You can also upload sandboxed notebooks to the web, such as on GitHub, and have others run them locally with a single command: `[](#__codelineno-11-1)uvx marimo edit --sandbox https://gist.githubusercontent.com/kolibril13/a59135dd0973b97d488ba21c650667fe/raw/5f98021b5d3c024d5827fa9464787517495178b4/marimo_minimal_numpy_example.py` **Note:** 1. This command will run code from a URL. Make sure you trust the source before proceeding. 2. Upon execution, you’ll be prompted: `[](#__codelineno-12-1)Would you like to run it in a secure docker container? [Y/n]:` To proceed securely, ensure you have [Docker](https://www.docker.com/) installed and running, then press `Y`. Specifying dependencies in Markdown files[¶](#specifying-dependencies-in-markdown-files "Permanent link") --------------------------------------------------------------------------------------------------------- Sandboxing support is also provided in [marimo's markdown file format](https://docs.marimo.io/guides/editor_features/watching/#as-markdown) under the `pyproject` entry of your frontmatter. `[](#__codelineno-13-1)--- [](#__codelineno-13-2)title: My Notebook [](#__codelineno-13-3)marimo-version: 0.0.0 [](#__codelineno-13-4)pyproject: | [](#__codelineno-13-5) requires-python: ">=3.11" [](#__codelineno-13-6) dependencies: [](#__codelineno-13-7) - pandas== [](#__codelineno-13-8) - altair== [](#__codelineno-13-9)---` Notebooks in existing projects - marimo https://docs.marimo.io/guides/package_management/notebooks_in_projects/ When working with notebooks in existing projects, there are two main approaches depending on your needs: 1. **Sandbox notebooks** - Self-contained notebooks with isolated dependencies 2. **Project notebooks** - Notebooks that are part of your project's environment marimo uses [PEP 723](https://peps.python.org/pep-0723/) inline script metadata for sandboxing, managed by uv. While sandboxing is currently exclusive to the uv package manager, other package managers may be supported in the future. For project notebooks, marimo can be added as a project dependency where all notebooks share the same environment defined in `pyproject.toml`. This approach works with uv and other package managers (Poetry, Pixi, Hatch, etc.). Sandbox notebooks (recommended for libraries)[¶](#sandbox-notebooks-recommended-for-libraries "Permanent link") --------------------------------------------------------------------------------------------------------------- Sandbox notebooks use inline script metadata ([PEP 723](https://peps.python.org/pep-0723/)) to create isolated environments. This is ideal when: * Building examples for a library that users can run independently * Creating notebooks that don't share dependencies with your main project * Sharing self-contained notebooks that work anywhere ### Basic sandbox notebook[¶](#basic-sandbox-notebook "Permanent link") Sandbox notebooks can be created with: `[](#__codelineno-0-1)marimo edit --sandbox notebook.py` When working in the notebook, marimo will automatically manage PEP 723 metadata for you. This metadata makes the notebook self-contained, meaning you can either come back later with marimo or run the notebook as a script directly with uv: `[](#__codelineno-1-1)marimo edit --sandbox notebook.py # automatically loads deps and launches marimo [](#__codelineno-1-2)uv run notebook.py # run notebook as a script` ### Developing against your local package[¶](#developing-against-your-local-package "Permanent link") When developing library examples, tutorials, or exploratory code, it's often useful to have notebooks that _use_ your library. In these cases, you can create and version sandboxed notebooks with your library as an _editable_ install. This approach lets you: * Test your library changes immediately without reinstalling * Add notebook-specific dependencies (like visualization or data processing tools) without polluting your library's requirements * Create self-contained examples that users can run without your development dependencies To add your library to a notebook, use uv: `[](#__codelineno-2-1)uv add --script notebooks/notebook.py . --editable` This will produce a header that looks like: `[](#__codelineno-3-1)# /// script [](#__codelineno-3-2)# requires-python = ">=3.11" [](#__codelineno-3-3)# dependencies = [ [](#__codelineno-3-4)# "my-package", [](#__codelineno-3-5)# "pandas", [](#__codelineno-3-6)# "matplotlib", [](#__codelineno-3-7)# ] [](#__codelineno-3-8)# [](#__codelineno-3-9)# [tool.uv.sources] [](#__codelineno-3-10)# my-package = { path = "../", editable = true } [](#__codelineno-3-11)# ///` Project notebooks[¶](#project-notebooks "Permanent link") --------------------------------------------------------- For notebooks that are integral to your project, you can manage everything through your project's `pyproject.toml`. This approach uses a single environment shared between your project and notebooks. ### Adding marimo to your project[¶](#adding-marimo-to-your-project "Permanent link") `[](#__codelineno-4-1)[project] [](#__codelineno-4-2)name = "my-project" [](#__codelineno-4-3)dependencies = [ [](#__codelineno-4-4) "numpy", [](#__codelineno-4-5) "requests", [](#__codelineno-4-6)] [](#__codelineno-4-7)[](#__codelineno-4-8)[dependency-groups] [](#__codelineno-4-9)dev = [ [](#__codelineno-4-10) "marimo", [](#__codelineno-4-11) "pytest", [](#__codelineno-4-12)]` Then work with notebooks using your project's environment: `[](#__codelineno-5-1)# Using uv [](#__codelineno-5-2)uv run marimo edit notebooks/analysis.py [](#__codelineno-5-3)[](#__codelineno-5-4)# Or activate the environment [](#__codelineno-5-5)source .venv/bin/activate [](#__codelineno-5-6)marimo edit notebooks/analysis.py` This approach: - Uses a single environment for everything - Shares dependencies between notebooks and your project - Follows standard Python project practices Importing from other directories If your notebooks need to import modules from directories outside your project, marimo supports configuring the Python path via `pyproject.toml`. However, when possible, it's preferred to avoid path manipulation. We recommend creating a package (`uv init --lib`) and including marimo as a development dependency. For multiple packages, consider configuring [uv workspaces](https://docs.astral.sh/uv/concepts/workspaces/). See the [runtime configuration guide](https://docs.marimo.io/guides/configuration/runtime_configuration/#python-path) for details. Examples[¶](#examples "Permanent link") --------------------------------------- ### Library with example notebooks[¶](#library-with-example-notebooks "Permanent link") When building a library, use sandbox notebooks for examples that users can run independently: `[](#__codelineno-6-1)my-library/ [](#__codelineno-6-2)├── pyproject.toml # Library dependencies [](#__codelineno-6-3)├── src/ [](#__codelineno-6-4)│ └── my_library/ [](#__codelineno-6-5)└── examples/ [](#__codelineno-6-6) ├── quickstart.py # Sandbox notebook [](#__codelineno-6-7) └── advanced.py # Sandbox notebook` Create example notebooks: `[](#__codelineno-7-1)# Initialize the project [](#__codelineno-7-2)uv init --lib my-library && cd my-library [](#__codelineno-7-3)[](#__codelineno-7-4)# Add marimo as development dependency [](#__codelineno-7-5)uv add --dev marimo [](#__codelineno-7-6)[](#__codelineno-7-7)# Create a sandbox notebook [](#__codelineno-7-8)mkdir examples [](#__codelineno-7-9)uv run marimo edit --sandbox examples/quickstart.py [](#__codelineno-7-10)[](#__codelineno-7-11)# Add your library as editable dependency [](#__codelineno-7-12)uv add --script examples/quickstart.py . --editable` ### Data science project[¶](#data-science-project "Permanent link") When notebooks are part of your analysis workflow, use project notebooks: `[](#__codelineno-8-1)analysis-project/ [](#__codelineno-8-2)├── pyproject.toml # Project + marimo dependencies [](#__codelineno-8-3)├── README.md [](#__codelineno-8-4)├── main.py # Created by uv init [](#__codelineno-8-5)└── notebook.py # Your marimo notebook` Set up the project: `[](#__codelineno-9-1)# Initialize project [](#__codelineno-9-2)uv init analysis-project && cd analysis-project [](#__codelineno-9-3)[](#__codelineno-9-4)# Add marimo as a project dependency [](#__codelineno-9-5)uv add marimo pandas scikit-learn [](#__codelineno-9-6)[](#__codelineno-9-7)# Edit notebooks using project environment [](#__codelineno-9-8)uv run marimo edit notebook.py` * [Using uv](https://docs.marimo.io/guides/package_management/using_uv/) - Detailed guide on uv with marimo * [Inlining dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/) - More on self-contained notebooks * [Package management overview](https://docs.marimo.io/guides/package_management/) - General package management in marimo Using uv - marimo https://docs.marimo.io/guides/package_management/using_uv/ [uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project manager: you can use it to install packages, manage the dependencies of Python projects, and run scripts. While marimo supports all major package managers, it integrates especially tightly with uv. In particular, marimo's package sandbox feature, which lets you [inline dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/) in notebook files, requires uv. No prior knowledge required This guide teaches you the basics of using `uv` with marimo. It assumes zero familiarity with `uv`. You can manage your notebooks' dependencies in three different ways: 1. inline dependencies: [inlining dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/) in notebook files, using `marimo edit --sandbox notebook.py` 2. projects: using a `uv` project , which define dependencies declaratively in a `pyproject.toml` file; 3. non-project environment: dependencies are imperatively installed We'll walk through each of these three ways in this guide. Using inline dependencies[¶](#using-inline-dependencies "Permanent link") ------------------------------------------------------------------------- The easiest way to get started is to use marimo's [package sandbox feature](https://docs.marimo.io/guides/package_management/inlining_dependencies/), which manages your dependencies for you. Create or edit your notebook with [`uvx` command](https://docs.astral.sh/uv/concepts/tools/#the-uv-tool-interface), making sure to include the `--sandbox` flag: `[](#__codelineno-0-1)uvx marimo edit --sandbox my_notebook.py` This command installs marimo in a temporary environment, activates it, then runs your marimo notebook. The `--sandbox` flag is what tells marimo to keep track of your dependencies and store them in the notebook file. If there are any dependencies already tracked in the file, this command will download them and install them in the environment. Run sandboxed notebooks as scripts with ### From URLs[¶](#from-urls "Permanent link") You can also upload sandboxed notebooks to the web, such as on GitHub, and have others run them locally with a single command: `[](#__codelineno-2-1)uvx marimo edit --sandbox https://gist.githubusercontent.com/kolibril13/a59135dd0973b97d488ba21c650667fe/raw/5f98021b5d3c024d5827fa9464787517495178b4/marimo_minimal_numpy_example.py` **Note:** 1. This command will run code from a URL. Make sure you trust the source before proceeding. 2. Upon execution, you’ll be prompted: `[](#__codelineno-3-1)Would you like to run it in a secure docker container? [Y/n]:` To proceed securely, ensure you have [Docker](https://www.docker.com/) installed and running, then press `Y`. To learn more, read our full guide on using [inline dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/). Using uv projects[¶](#using-uv-projects "Permanent link") --------------------------------------------------------- A [`uv` project](https://docs.astral.sh/uv/guides/projects/) is a directory in which you can store Python code, including notebooks, alongside a pyproject.toml file that declares the project's dependencies. ### Creating a project[¶](#creating-a-project "Permanent link") Create a project with `uv init`: `[](#__codelineno-4-1)uv init hello-world [](#__codelineno-4-2)cd hello-world` This creates a pyproject.toml and some starter code. Next, add marimo to your project: Omitting marimo from your project Adding marimo to your project is optional. Instead, you can run marimo in a temporary environment that has access to your project's dependencies using `uv run --with marimo marimo edit`. ### Running marimo[¶](#running-marimo "Permanent link") Once you've added marimo, use the `uv run` command to run the version of marimo installed in your project: `[](#__codelineno-6-1)uv run marimo edit my_notebook.py` Starting marimo in this way will let marimo import any of the packages installed in your project. **Scripts.** Run marimo notebooks as scripts with which will run your notebook in an environment containing your project dependencies. ### Adding and removing dependencies[¶](#adding-and-removing-dependencies "Permanent link") #### Using the uv command-line[¶](#using-the-uv-command-line "Permanent link") Use `uv add` to add dependencies: You can also specify a version Remove packages with `uv remove`: #### Using the marimo editor[¶](#using-the-marimo-editor "Permanent link") If you started marimo with `uv run marimo edit`, the marimo editor's [package management features](https://docs.marimo.io/guides/package_management/installing_packages/) will add and remove packages from your pyproject.toml, so there's no need to use the `uv` command-line if you don't want to. Using marimo in a non-project environment[¶](#using-marimo-in-a-non-project-environment "Permanent link") --------------------------------------------------------------------------------------------------------- If you are used to a venv and pip based workflow, you can use the `uv venv` and `uv pip` commands for a similar but more performant experience: * `uv venv` creates a virtual environment in the current directory, at `.venv` * `uv pip` lets you install and uninstall packages in the venv ### Example[¶](#example "Permanent link") `[](#__codelineno-11-1)$ uv venv [](#__codelineno-11-2)$ uv pip install numpy [](#__codelineno-11-3)$ uv pip install marimo [](#__codelineno-11-4)$ uv run marimo edit` From here, `import numpy` will work within the notebook, and marimo's UI installer will add packages to the environment with `uv pip install` on your behalf. Generate with AI - marimo https://docs.marimo.io/guides/generate_with_ai/ Generate notebooks with AI[¶](#generate-notebooks-with-ai "Permanent link") --------------------------------------------------------------------------- | Guide | Description | | --- | --- | | [Zero-shot entire notebooks](https://docs.marimo.io/guides/generate_with_ai/text_to_notebook/) | Generate entire notebooks with AI | | [AI-assisted coding](https://docs.marimo.io/guides/editor_features/ai_completion/) | Refactor code and generate cells with AI | | [Prompts for the marimo editor](https://docs.marimo.io/guides/generate_with_ai/prompts/) | Collection of prompts to speed up workflows in marimo | Generate entire notebooks - marimo https://docs.marimo.io/guides/generate_with_ai/text_to_notebook/ Use [`marimo new`](https://docs.marimo.io/cli/#marimo-new) at the command line to generate entirely new notebooks using an LLM. For example, type `[](#__codelineno-0-1)marimo new "Plot an interactive 3D surface with matplotlib."` to open a freshly generated notebook in your browser. For long prompts, you can pass a text file instead: marimo's AI knows how to use marimo-specific UI elements and popular libraries for working with data. To get inspired, visit [https://marimo.app/ai](https://marimo.app/ai). Some of our favorites: * [Dimensionality reduction](https://marimo.app/ai?q=Show+me+how+to+visualize+handwritten+digits+in+two+dimensions%2C+using+an+Altair+scatterplot.+Include+a+cell+that+shows+the+chart+value.+Make+the+chart+render+as+a+square.) * [Smooth a time series](https://marimo.app/ai?q=Show+me+how+to+smooth+time+series+data+and+plot+it.+Use+a+well-known+stock+dataset+and+make+it+interactive) * [Compute code complexity](https://marimo.app/ai?q=Build+a+tool+that+analyzes+Python+code+complexity+metrics+like+cyclomatic+complexity.+Let+me+input+code+snippets+and+see+visualizations+of+the+results.) * [Visualize sorting algorithms](https://marimo.app/ai?q=Plot+an+interesting+3D+surface+with+matplotlib.+Include+an+interactive+element+to+control+the+shape+of+the+surface.) Prompts for the marimo editor - marimo https://docs.marimo.io/guides/generate_with_ai/prompts/ marimo offers many tools for [AI assisted coding](https://docs.marimo.io/guides/editor_features/ai_completion/). However, sometimes you may want to do something more custom and could benefit from a prompt template to get started from. The goal of this page is to share prompts that have proven to be useful and will help you get started on specific tasks. You can add these prompts to your [custom rules](https://docs.marimo.io/guides/editor_features/ai_completion/#custom-rules) but be mindful that doing so will make every call to the LLM more expensive because you're feeding it more tokens. That's why we generally recommend to start your conversations with these snippets if you don't plan on using them very often. CLAUDE.md[¶](#claudemd "Permanent link") ---------------------------------------- You can run [claude code](https://www.anthropic.com/claude-code) in the terminal and ask it to edit a marimo notebook on your behalf. Make sure that you run your notebook with the [watch flag](https://docs.marimo.io/api/watch/) turned on, like `marimo edit --watch notebook.py`, to see updates appear live whenever claude makes a change. To help claude code, you might want to take the snippet below as starting context for your `CLAUDE.md` file. This snippet should be seen as a starting point and we recommend adding extra context yourself. Things like "prefer polars over pandas" to indicate your preferred libraries and tools. `[](#__codelineno-0-1)curl https://docs.marimo.io/CLAUDE.md > CLAUDE.md` Example CLAUDE.md file `[](#__codelineno-1-1)# Marimo notebook assistant [](#__codelineno-1-2)[](#__codelineno-1-3)I am a specialized AI assistant designed to help create data science notebooks using marimo. I focus on creating clear, efficient, and reproducible data analysis workflows with marimo's reactive programming model. [](#__codelineno-1-4)[](#__codelineno-1-5)If you make edits to the notebook, only edit the contents inside the function decorator with @app.cell. [](#__codelineno-1-6)marimo will automatically handle adding the parameters and return statement of the function. For example, [](#__codelineno-1-7)for each edit, just return:` @app.cell def _(): return ``[](#__codelineno-2-1)## Marimo fundamentals [](#__codelineno-2-2)[](#__codelineno-2-3)Marimo is a reactive notebook that differs from traditional notebooks in key ways: [](#__codelineno-2-4)[](#__codelineno-2-5)- Cells execute automatically when their dependencies change [](#__codelineno-2-6)- Variables cannot be redeclared across cells [](#__codelineno-2-7)- The notebook forms a directed acyclic graph (DAG) [](#__codelineno-2-8)- The last expression in a cell is automatically displayed [](#__codelineno-2-9)- UI elements are reactive and update the notebook automatically [](#__codelineno-2-10)[](#__codelineno-2-11)## Code Requirements [](#__codelineno-2-12)[](#__codelineno-2-13)1. All code must be complete and runnable [](#__codelineno-2-14)2. Follow consistent coding style throughout [](#__codelineno-2-15)3. Include descriptive variable names and helpful comments [](#__codelineno-2-16)4. Import all modules in the first cell, always including `import marimo as mo` [](#__codelineno-2-17)5. Never redeclare variables across cells [](#__codelineno-2-18)6. Ensure no cycles in notebook dependency graph [](#__codelineno-2-19)7. The last expression in a cell is automatically displayed, just like in Jupyter notebooks. [](#__codelineno-2-20)8. Don't include comments in markdown cells [](#__codelineno-2-21)9. Don't include comments in SQL cells [](#__codelineno-2-22)10. Never define anything using `global`. [](#__codelineno-2-23)[](#__codelineno-2-24)## Reactivity [](#__codelineno-2-25)[](#__codelineno-2-26)Marimo's reactivity means: [](#__codelineno-2-27)[](#__codelineno-2-28)- When a variable changes, all cells that use that variable automatically re-execute [](#__codelineno-2-29)- UI elements trigger updates when their values change without explicit callbacks [](#__codelineno-2-30)- UI element values are accessed through `.value` attribute [](#__codelineno-2-31)- You cannot access a UI element's value in the same cell where it's defined [](#__codelineno-2-32)- Cells prefixed with an underscore (e.g. _my_var) are local to the cell and cannot be accessed by other cells [](#__codelineno-2-33)[](#__codelineno-2-34)## Best Practices [](#__codelineno-2-35)[](#__codelineno-2-36) [](#__codelineno-2-37)[](#__codelineno-2-38)- Use polars for data manipulation [](#__codelineno-2-39)- Implement proper data validation [](#__codelineno-2-40)- Handle missing values appropriately [](#__codelineno-2-41)- Use efficient data structures [](#__codelineno-2-42)- A variable in the last expression of a cell is automatically displayed as a table [](#__codelineno-2-43) [](#__codelineno-2-44)[](#__codelineno-2-45) [](#__codelineno-2-46)- For matplotlib: use plt.gca() as the last expression instead of plt.show() [](#__codelineno-2-47)- For plotly: return the figure object directly [](#__codelineno-2-48)- For altair: return the chart object directly. Add tooltips where appropriate. You can pass polars dataframes directly to altair. [](#__codelineno-2-49)- Include proper labels, titles, and color schemes [](#__codelineno-2-50)- Make visualizations interactive where appropriate [](#__codelineno-2-51) [](#__codelineno-2-52)[](#__codelineno-2-53) [](#__codelineno-2-54)[](#__codelineno-2-55)- Access UI element values with .value attribute (e.g., slider.value) [](#__codelineno-2-56)- Create UI elements in one cell and reference them in later cells [](#__codelineno-2-57)- Create intuitive layouts with mo.hstack(), mo.vstack(), and mo.tabs() [](#__codelineno-2-58)- Prefer reactive updates over callbacks (marimo handles reactivity automatically) [](#__codelineno-2-59)- Group related UI elements for better organization [](#__codelineno-2-60) [](#__codelineno-2-61)[](#__codelineno-2-62) [](#__codelineno-2-63)- When writing duckdb, prefer using marimo's SQL cells, which start with df = mo.sql(f"""""") for DuckDB, or df = mo.sql(f"""""", engine=engine) for other SQL engines. [](#__codelineno-2-64)- See the SQL with duckdb example for an example on how to do this [](#__codelineno-2-65)- Don't add comments in cells that use mo.sql() [](#__codelineno-2-66) [](#__codelineno-2-67)[](#__codelineno-2-68)## Troubleshooting [](#__codelineno-2-69)[](#__codelineno-2-70)Common issues and solutions: [](#__codelineno-2-71)[](#__codelineno-2-72)- Circular dependencies: Reorganize code to remove cycles in the dependency graph [](#__codelineno-2-73)- UI element value access: Move access to a separate cell from definition [](#__codelineno-2-74)- Visualization not showing: Ensure the visualization object is the last expression [](#__codelineno-2-75)[](#__codelineno-2-76)After generating a notebook, run `marimo check --fix` to catch and [](#__codelineno-2-77)automatically resolve common formatting issues, and detect common pitfalls. [](#__codelineno-2-78)[](#__codelineno-2-79)## Available UI elements [](#__codelineno-2-80)[](#__codelineno-2-81)- `mo.ui.altair_chart(altair_chart)` [](#__codelineno-2-82)- `mo.ui.button(value=None, kind='primary')` [](#__codelineno-2-83)- `mo.ui.run_button(label=None, tooltip=None, kind='primary')` [](#__codelineno-2-84)- `mo.ui.checkbox(label='', value=False)` [](#__codelineno-2-85)- `mo.ui.date(value=None, label=None, full_width=False)` [](#__codelineno-2-86)- `mo.ui.dropdown(options, value=None, label=None, full_width=False)` [](#__codelineno-2-87)- `mo.ui.file(label='', multiple=False, full_width=False)` [](#__codelineno-2-88)- `mo.ui.number(value=None, label=None, full_width=False)` [](#__codelineno-2-89)- `mo.ui.radio(options, value=None, label=None, full_width=False)` [](#__codelineno-2-90)- `mo.ui.refresh(options: List[str], default_interval: str)` [](#__codelineno-2-91)- `mo.ui.slider(start, stop, value=None, label=None, full_width=False, step=None)` [](#__codelineno-2-92)- `mo.ui.range_slider(start, stop, value=None, label=None, full_width=False, step=None)` [](#__codelineno-2-93)- `mo.ui.table(data, columns=None, on_select=None, sortable=True, filterable=True)` [](#__codelineno-2-94)- `mo.ui.text(value='', label=None, full_width=False)` [](#__codelineno-2-95)- `mo.ui.text_area(value='', label=None, full_width=False)` [](#__codelineno-2-96)- `mo.ui.data_explorer(df)` [](#__codelineno-2-97)- `mo.ui.dataframe(df)` [](#__codelineno-2-98)- `mo.ui.plotly(plotly_figure)` [](#__codelineno-2-99)- `mo.ui.tabs(elements: dict[str, mo.ui.Element])` [](#__codelineno-2-100)- `mo.ui.array(elements: list[mo.ui.Element])` [](#__codelineno-2-101)- `mo.ui.form(element: mo.ui.Element, label='', bordered=True)` [](#__codelineno-2-102)[](#__codelineno-2-103)## Layout and utility functions [](#__codelineno-2-104)[](#__codelineno-2-105)- `mo.md(text)` - display markdown [](#__codelineno-2-106)- `mo.stop(predicate, output=None)` - stop execution conditionally [](#__codelineno-2-107)- `mo.output.append(value)` - append to the output when it is not the last expression [](#__codelineno-2-108)- `mo.output.replace(value)` - replace the output when it is not the last expression [](#__codelineno-2-109)- `mo.Html(html)` - display HTML [](#__codelineno-2-110)- `mo.image(image)` - display an image [](#__codelineno-2-111)- `mo.hstack(elements)` - stack elements horizontally [](#__codelineno-2-112)- `mo.vstack(elements)` - stack elements vertically [](#__codelineno-2-113)- `mo.tabs(elements)` - create a tabbed interface [](#__codelineno-2-114)[](#__codelineno-2-115)## Examples [](#__codelineno-2-116)[](#__codelineno-2-117)`` @app.cell def \_(): mo.md(""" # Hello world This is a \_markdown_ **cell**. """) return `[](#__codelineno-3-1) [](#__codelineno-3-2)[](#__codelineno-3-3)` @app.cell def \_(): import marimo as mo import altair as alt import polars as pl import numpy as np return @app.cell def \_(): n\_points = mo.ui.slider(10, 100, value=50, label="Number of points") n\_points return @app.cell def \_(): x = np.random.rand(n\_points.value) y = np.random.rand(n\_points.value) `df = pl.DataFrame({"x": x, "y": y}) chart = alt.Chart(df).mark_circle(opacity=0.7).encode( x=alt.X('x', title='X axis'), y=alt.Y('y', title='Y axis') ).properties( title=f"Scatter plot with {n_points.value} points", width=400, height=300 ) chart return` `[](#__codelineno-4-1) [](#__codelineno-4-2)[](#__codelineno-4-3)` @app.cell def \_(): import marimo as mo import polars as pl from vega\_datasets import data return @app.cell def \_(): cars\_df = pl.DataFrame(data.cars()) mo.ui.data\_explorer(cars\_df) return `[](#__codelineno-5-1) [](#__codelineno-5-2)[](#__codelineno-5-3)` @app.cell def \_(): import marimo as mo import polars as pl import altair as alt return @app.cell def \_(): iris = pl.read\_csv("hf://datasets/scikit-learn/iris/Iris.csv") return @app.cell def \_(): species\_selector = mo.ui.dropdown( options=\["All"\] + iris\["Species"\].unique().to\_list(), value="All", label="Species", ) x\_feature = mo.ui.dropdown( options=iris.select(pl.col(pl.Float64, pl.Int64)).columns, value="SepalLengthCm", label="X Feature", ) y\_feature = mo.ui.dropdown( options=iris.select(pl.col(pl.Float64, pl.Int64)).columns, value="SepalWidthCm", label="Y Feature", ) mo.hstack(\[species\_selector, x\_feature, y\_feature\]) return @app.cell def \_(): filtered\_data = iris if species\_selector.value == "All" else iris.filter(pl.col("Species") == species\_selector.value) `chart = alt.Chart(filtered_data).mark_circle().encode( x=alt.X(x_feature.value, title=x_feature.value), y=alt.Y(y_feature.value, title=y_feature.value), color='Species' ).properties( title=f"{y_feature.value} vs {x_feature.value}", width=500, height=400 ) chart return` `[](#__codelineno-6-1) [](#__codelineno-6-2)[](#__codelineno-6-3)` @app.cell def \_(): mo.stop(not data.value, mo.md("No data to display")) `if mode.value == "scatter": mo.output.replace(render_scatter(data.value)) else: mo.output.replace(render_bar_chart(data.value)) return` `[](#__codelineno-7-1) [](#__codelineno-7-2)[](#__codelineno-7-3)` @app.cell def \_(): import marimo as mo import altair as alt import polars as pl return @app.cell def \_(): # Load dataset weather = pl.read\_csv("[https://raw.githubusercontent.com/vega/vega-datasets/refs/heads/main/data/weather.csv](https://raw.githubusercontent.com/vega/vega-datasets/refs/heads/main/data/weather.csv)") weather\_dates = weather.with\_columns( pl.col("date").str.strptime(pl.Date, format="%Y-%m-%d") ) \_chart = ( alt.Chart(weather\_dates) .mark\_point() .encode( x="date:T", y="temp\_max", color="location", ) ) return @app.cell def \_(): chart = mo.ui.altair\_chart(\_chart) chart return @app.cell def \_(): # Display the selection chart.value return `[](#__codelineno-8-1) [](#__codelineno-8-2)[](#__codelineno-8-3)` @app.cell def \_(): import marimo as mo return @app.cell def \_(): first\_button = mo.ui.run\_button(label="Option 1") second\_button = mo.ui.run\_button(label="Option 2") \[first\_button, second\_button\] return @app.cell def \_(): if first\_button.value: print("You chose option 1!") elif second\_button.value: print("You chose option 2!") else: print("Click a button!") return `[](#__codelineno-9-1) [](#__codelineno-9-2)[](#__codelineno-9-3)` @app.cell def \_(): import marimo as mo import polars as pl return @app.cell def \_(): weather = pl.read\_csv('[https://raw.githubusercontent.com/vega/vega-datasets/refs/heads/main/data/weather.csv](https://raw.githubusercontent.com/vega/vega-datasets/refs/heads/main/data/weather.csv)') return @app.cell def \_(): seattle\_weather\_df = mo.sql( f""" SELECT \* FROM weather WHERE location = 'Seattle'; """ ) return If you want to generate [custom UIs or widgets for marimo](https://docs.marimo.io/api/inputs/anywidget/#building-custom-ui-elements) then anywidget is the way to go. Because anywidget is a fairly recent project, LLMs have been known to hallucinate when you try to generate custom widgets from scratch. The following prompt contains an example that helps prevent this behaviour and it also points out common failure scenarios that the LLM should avoid. ``[](#__codelineno-11-1)When writing an anywidget use vanilla javascript in `_esm` and do not forget about `_css`. The css should look bespoke in light mode and dark mode. Keep the css small unless explicitly asked to go the extra mile. When you display the widget it must be wrapped via `widget = mo.ui.anywidget(OriginalAnywidget())`. [](#__codelineno-11-2)[](#__codelineno-11-3) [](#__codelineno-11-4)import anywidget [](#__codelineno-11-5)import traitlets [](#__codelineno-11-6) [](#__codelineno-11-7)[](#__codelineno-11-8)class CounterWidget(anywidget.AnyWidget): [](#__codelineno-11-9) _esm = """ [](#__codelineno-11-10) // Define the main render function [](#__codelineno-11-11) function render({ model, el }) { [](#__codelineno-11-12) let count = () => model.get("number"); [](#__codelineno-11-13) let btn = document.createElement("button"); [](#__codelineno-11-14) btn.innerHTML = `count is ${count()}`; [](#__codelineno-11-15) btn.addEventListener("click", () => { [](#__codelineno-11-16) model.set("number", count() + 1); [](#__codelineno-11-17) model.save_changes(); [](#__codelineno-11-18) }); [](#__codelineno-11-19) model.on("change:number", () => { [](#__codelineno-11-20) btn.innerHTML = `count is ${count()}`; [](#__codelineno-11-21) }); [](#__codelineno-11-22) el.appendChild(btn); [](#__codelineno-11-23) } [](#__codelineno-11-24) // Important! We must export at the bottom here! [](#__codelineno-11-25) export default { render }; [](#__codelineno-11-26) """ [](#__codelineno-11-27) _css = """button{ [](#__codelineno-11-28) font-size: 14px; [](#__codelineno-11-29) }""" [](#__codelineno-11-30) number = traitlets.Int(0).tag(sync=True) [](#__codelineno-11-31)[](#__codelineno-11-32)widget = mo.ui.anywidget(CounterWidget()) [](#__codelineno-11-33)widget [](#__codelineno-11-34)[](#__codelineno-11-35)# Grabbing the widget from another cell, `.value` is a dictionary. [](#__codelineno-11-36)print(widget.value["number"]) [](#__codelineno-11-37) [](#__codelineno-11-38)[](#__codelineno-11-39)When sharing the anywidget, keep the example minimal. No need to combine it with marimo ui elements unless explicitly stated to do so.`` Editor features - marimo https://docs.marimo.io/guides/editor_features/ The **marimo editor** is the browser-based IDE in which you write marimo notebooks. We've taken a batteries-included approach to designing the editor: it comes _packed_ with features to make you productive when working with code and data. | Guide | Description | | --- | --- | | [Overview](https://docs.marimo.io/guides/editor_features/overview/) | An overview of editor features and configuration | | [Understanding dataflow](https://docs.marimo.io/guides/editor_features/dataflow/) | Visualize and navigate cell dependencies | | [Package Management](https://docs.marimo.io/guides/editor_features/package_management/) | Using package managers in marimo | | [AI Completion](https://docs.marimo.io/guides/editor_features/ai_completion/) | Code with the help of a language model | | [Language Server](https://docs.marimo.io/guides/editor_features/language_server/) | Code intelligence via LSP | | [Hotkeys](https://docs.marimo.io/guides/editor_features/hotkeys/) | Our hotkeys | Highlights include: * [dataflow tools](https://docs.marimo.io/guides/editor_features/dataflow/) including a variables panel, dependency graph, and minimap for understanding notebook structure * a data explorer that lets you inspect dataframes and tables at a glance * smart module autoreloading that tells you which cells need to be rerun * code completion * GitHub Copilot * language-model assisted coding * language server protocol (LSP) for diagnostics and code intelligence * vim keybindings * live documentation preiews as you type and much more. AI-assisted coding - marimo https://docs.marimo.io/guides/editor_features/ai_completion/ marimo is an AI-native editor, with support for full-cell AI code generation: * generating new cells from a prompt * refactoring existing cells from a prompt * generating entire notebooks as well as inline autocompletion (like GitHub Copilot). marimo's AI assistant is specialized for working with data: unlike traditional assistants that only have access to the text of your program, marimo's assistant has access to the values of variables in memory, letting it code against your dataframe and database schemas. This guide provides an overview of these features and how to configure them. Locating your marimo.toml config file Various instructions in this guide refer to the marimo.toml configuration file. Locate this file with `marimo config show | head`. Generating cells with AI[¶](#generating-cells-with-ai "Permanent link") ----------------------------------------------------------------------- marimo has built-in support for generating and refactoring code with LLMs. marimo works with hosted AI providers, such as OpenAI, Anthropic, and Google, as well as local models served via Ollama. **Enabling AI code generation.** To enable AI code generation, first install required dependencies through the notebook settings. Install required dependencies for AI generation through the notebook settings. Then configure your LLM provider through the AI tab in the settings menu; see the section on [connecting your LLM](#connecting-to-an-llm) for detailed instructions. ### Variable context[¶](#variable-context "Permanent link") marimo's AI assistant has your notebook code as context. You can additionally pass variables and their values to the assistant by referencing them by name with `@`. For example, to include the columns of a dataframe `df` in your prompt, write `@df`. Pass variables to your prompt by tagging them with \`@\`. ### Refactor existing cells[¶](#refactor-existing-cells "Permanent link") Make edits to an existing cell by hitting `Ctrl/Cmd-shift-e`, which opens a prompt box that has your cell's code as input. Use AI to modify a cell by pressing \`Ctrl/Cmd-Shift-e\`. ### Generate new cells[¶](#generate-new-cells "Permanent link") #### Generate with AI button[¶](#generate-with-ai-button "Permanent link") At the bottom of every notebook is a button titled "Generate with AI". Click this button to add entirely new cells to your notebook. #### Chat panel[¶](#chat-panel "Permanent link") The chat panel on the left sidebar lets you chat with an LLM and ask questions aboutyour notebook. The LLM can also generate code cells that you can insert into your notebook. The chat panel currently supports the following modes: * **Manual**: No tool access; the AI responds based only on the conversation and manually injected context * **Ask**: Enables read-only [AI tools](https://docs.marimo.io/guides/editor_features/tools/) and [tools from added MCP Client servers](https://docs.marimo.io/guides/editor_features/mcp/#mcp-client) for context gathering, allowing the assistant to inspect your notebooks * **Agent** (beta): Enables all tools in **Ask Mode** plus additional tools to [edit notebook cells (add, remove, update) and run stale cells](https://docs.marimo.io/guides/editor_features/tools/#editing-agent-mode-only). See the chat panel in action ### Generating entire notebooks[¶](#generating-entire-notebooks "Permanent link") Generate entire notebooks with `marimo new PROMPT` at the command-line; see the [text-to-notebook docs](https://docs.marimo.io/guides/generate_with_ai/text_to_notebook/) to learn more. ### Custom rules[¶](#custom-rules "Permanent link") You can customize how the AI assistant behaves by adding rules in the marimo settings. These rules help ensure consistent code generation across all AI providers. You can find more information about marimo's supported plotting libraries and data handling in the [plotting guide](https://docs.marimo.io/guides/working_with_data/plotting/#plotting) and [working with data guide](https://docs.marimo.io/guides/working_with_data/). Configure custom AI rules in settings For example, you can add rules about: * Preferred plotting libraries (matplotlib, plotly, altair) * Data handling practices * Code style conventions * Error handling preferences Example custom rules: `[](#__codelineno-0-1)Use plotly for interactive visualizations and matplotlib for static plots [](#__codelineno-0-2)Prefer polars over pandas for data manipulation due to better performance [](#__codelineno-0-3)Include docstrings for all functions using NumPy style [](#__codelineno-0-4)Use Type hints for all function parameters and return values [](#__codelineno-0-5)Handle errors with try/except blocks and provide informative error messages [](#__codelineno-0-6)Follow PEP 8 style guidelines [](#__codelineno-0-7)When working with data: [](#__codelineno-0-8)- Use altair, plotly for declarative visualizations [](#__codelineno-0-9)- Prefer polars over pandas [](#__codelineno-0-10)- Ensure proper error handling for data operations [](#__codelineno-0-11)For plotting: [](#__codelineno-0-12)- Use px.scatter for scatter plots [](#__codelineno-0-13)- Use px.line for time series [](#__codelineno-0-14)- Include proper axis labels and titles [](#__codelineno-0-15)- Set appropriate color schemes` ### Connecting to an LLM[¶](#connecting-to-an-llm "Permanent link") You can connect to an LLM through the notebook settings menu, or by manually editing your `marimo.toml` configuration file. **Prefer going through the notebook settings menu.** You can configure the following providers: * OpenAI * Anthropic * AWS Bedrock * Google AI * GitHub * Ollama * and any OpenAI-compatible provider See the [llm\_providers](https://docs.marimo.io/guides/configuration/llm_providers/) guide for detailed instructions on how to configure each provider. Agents[¶](#agents "Permanent link") ----------------------------------- Experimental: Agents marimo also supports external AI agents like Claude Code and Gemini CLI that can interact with your notebooks. Learn more in the [agents](https://docs.marimo.io/guides/editor_features/agents/) guide. Copilots[¶](#copilots "Permanent link") --------------------------------------- Copilots allow you to tab-complete code based on your notebook's context, similar to editors like Cursor. ### GitHub Copilot[¶](#github-copilot "Permanent link") The marimo editor natively supports [GitHub Copilot](https://copilot.github.com/), an AI pair programmer, similar to VS Code: 1. Install [Node.js](https://nodejs.org/en/download). 2. Enable Copilot via the settings menu in the marimo editor. Follow these instructions. _GitHUb Copilot is not yet available in our conda distribution; please install marimo using `pip`/`uv` if you need Copilot._ ### Windsurf Copilot[¶](#windsurf-copilot "Permanent link") [Windsurf](https://windsurf.com/) (formerly codeium) provides tab-completion tooling that can also be used from within marimo. To set up Windsurf: 1. Go to [windsurf.com](https://windsurf.com/) website and sign up for an account. 2. Download the [Windsurf app](https://windsurf.com/download). 3. After installing Windsurf and authenticating, open up the command palette, via cmd+shift+p, and ask it to copy the api key to your clipboard. 4a. Configure the UI settings in the editor to use Windsurf. 4b. Alternatively you can also configure the api key from the marimo config file. marimo.toml `[](#__codelineno-1-1)[completion] [](#__codelineno-1-2)copilot = "codeium" [](#__codelineno-1-3)codeium_api_key = ""` ### Custom copilots[¶](#custom-copilots "Permanent link") marimo also supports integrating with custom LLM providers for code completion suggestions. This allows you to use your own LLM service to provide in-line code suggestions based on internal providers or local models (e.g. Ollama). You may also use OpenAI, Anthropic, Google, or any other providers by providing your own API keys and configuration. To configure a custom copilot: 1. Ensure you have an LLM provider that offers API access for code completion (either external or running locally) 2. Add the following configuration to your `marimo.toml` (or configure in the UI settings in the editor): marimo.toml `[](#__codelineno-2-1)[ai.models] [](#__codelineno-2-2)autocomplete_model = "provider/model-name" [](#__codelineno-2-3)[](#__codelineno-2-4)[completion] [](#__codelineno-2-5)copilot = "custom"` The configuration options include: * `autocomplete_model`: The specific model to use for inline autocompletion. * `copilot`: The name of the copilot to use for code generation. Editor overview - marimo https://docs.marimo.io/guides/editor_features/overview/ This guide introduces some of marimo editor's features, including a variables panel, dependency graph viewer, table of contents, HTML export, GitHub copilot, code formatting, a feedback form, and more. Configuration[¶](#configuration "Permanent link") ------------------------------------------------- The editor exposes of a number of settings for the current notebook, as well as user-wide configuration that will apply to all your notebooks. These settings include the option to display the current notebook in full width, to use vim keybindings, to enable GitHub copilot, and more. To access these settings, click the gear icon in the top-right of the editor: A non-exhaustive list of settings: * [Command mode](#command-mode) * Outputs above or below code cells * [Disable/enable autorun](https://docs.marimo.io/guides/reactivity/#configuring-how-marimo-runs-cells) * Package installation * [Vim keybindings](#vim-keybindings) * Dark mode * Auto-save * Auto-complete * Editor font-size * Code formatting with ruff/black * [GitHub Copilot](https://docs.marimo.io/guides/editor_features/ai_completion/) * [LLM coding assistant](https://docs.marimo.io/guides/editor_features/ai_completion/) * [Module autoreloading](https://docs.marimo.io/guides/configuration/runtime_configuration/#on-module-change) * [Reactive reference highlighting](https://docs.marimo.io/guides/editor_features/dataflow/#reactive-reference-highlighting) Command mode[¶](#command-mode "Permanent link") ----------------------------------------------- marimo distinguishes between editing cell content and working with cells at the notebook level. **Command mode** lets you navigate, select, and manipulate _cells_ rather than editing their contents. **Enter/Exit:** * Enter command mode: `Esc` (from cell editor) or `Ctrl+Esc`/`Cmd+Esc` (when vim keybindings are enabled, `Shift+Esc` on Windows) * Exit command mode: `Enter` or click on a cell **Shortcuts:** * `↓`/`↑` - navigate cells * `Shift+↓`/`Shift+↑` - multi-select cells * `Enter` - edit selected cell * `a`/`b` - new cell above/below * `c`/`v` - copy/paste cells * `s` - save notebook * `Shift+Enter` - run cell and move to next * `Ctrl/Cmd+↑` / `Ctrl/Cmd+↓` - jump to top/bottom of notebook When [vim keybindings](#vim-keybindings) are enabled, additional shortcuts are available. ### Vim keybindings[¶](#vim-keybindings "Permanent link") marimo supports vim keybindings that extend to notebook editing. Within cells, use standard vim modes. Press `Ctrl+Esc` (or `Cmd+Esc` on macOS, `Shift+Esc` on Windows) from normal mode to enter [command mode](#command-mode) for notebook navigation. **Cell editing additions:** * `gd` - go to definition * `dd` - delete empty cell * `:w` - save notebook **Custom vimrc:** You can customize your vim experience by adding a `.vimrc` configuration in the user settings or pyproject.toml User configpyproject.toml marimo.toml `[](#__codelineno-0-1)[keymap] [](#__codelineno-0-2)vimrc = /User/absolute/path/to/.vimrc` pyproject.toml `[](#__codelineno-1-1)[tool.marimo.keymap] [](#__codelineno-1-2)vimrc = relative/path/.vimrc` **Command mode additions:** When vim keybindings are enabled, press `Ctrl+Esc` (or `Cmd+Esc` on macOS, `Shift+Esc` on Windows) from normal mode to enter [command mode](#command-mode) with additional vim-specific keybindings: * `j`/`k` - navigate cells * `gg`/`G` - first/last cell * `Shift+j`/`k` - extend selection * `dd` - delete cell * `yy` - copy cell * `p`/`P` - paste below/above * `o`/`O` - new cell below/above * `u` - undo deletion * `i` - edit cell (i.e., return to normal mode) Press `i` or `Enter` to return to cell editing. Overview panels[¶](#overview-panels "Permanent link") ----------------------------------------------------- marimo ships with the IDE panels that provide an overview of your notebook * **file explorer**: view the file tree, open other notebooks * **variables**: explore variable values, see where they are defined and used, with go-to-definition * **data explorer**: see dataframe and table schemas at a glance * **dataflow tools**: visualize and navigate notebook structure and cell dependencies (see [Understanding dataflow](https://docs.marimo.io/guides/editor_features/dataflow/)) * **package manager**: add and remove packages, and view your current environment * **table of contents**: corresponding to your markdown * **documentation** - move your text cursor over a symbol to see its documentation * **logs**: a continuous stream of stdout and stderr * **scratchpad**: a scratchpad cell where you can execute throwaway code * **snippets** - searchable snippets to copy directly into your notebook * **feedback** - share feedback! These panels can be toggled via the buttons in the left of the editor. Cell actions[¶](#cell-actions "Permanent link") ----------------------------------------------- Click the three dots in the top right of a cell to pull up a context menu, letting you format code, hide code, send a cell to the top or bottom of the notebook, give the cell a name, and more. Drag a cell using the vertical dots to the right of the cell. marimo supports context-sensitive right-click menus in various locations of the editor. Right-click on a cell to open a context-sensitive menu; right click on the create-cell button (the plus icon) to get options for the cell type to create. Go-to-definition[¶](#go-to-definition "Permanent link") ------------------------------------------------------- * Click on a variable in the editor to see where it's defined and used * `Cmd/Ctrl-Click` on a variable to jump to its definition * Right-click on a variable to see a context menu with options to jump to its definition Keyboard shortcuts[¶](#keyboard-shortcuts "Permanent link") ----------------------------------------------------------- We've kept some well-known [keyboard shortcuts](https://docs.marimo.io/guides/editor_features/hotkeys/) for notebooks (`Ctrl-Enter`, `Shift-Enter`), dropped others, and added a few of our own. Hit `Ctrl/Cmd-Shift-H` to pull up the shortcuts. We know keyboard shortcuts are very personal; you can remap them in the configuration. _Missing a shortcut? File a [GitHub issue](https://github.com/marimo-team/marimo/issues)._ Command palette[¶](#command-palette "Permanent link") ----------------------------------------------------- Hit `Cmd/Ctrl+K` to open the command palette. Quickly access common commands with the command palette. _Missing a command? File a [GitHub issue](https://github.com/marimo-team/marimo/issues)._ Editor widths[¶](#editor-widths "Permanent link") ------------------------------------------------- You can set the width of the editor in the notebook settings: * **Compact**: A narrow width with generous margins, ideal for reading * **Wide**: A wider layout that gives more space for content * **Full**: Uses the full width of your browser window, ideal for dashboard-style notebooks * **Multi-column**: Splits your notebook into multiple columns, letting you view and edit cells side-by-side. This is only possible because marimo models your notebook as a directed acyclic graph (DAG) and the [execution order](https://docs.marimo.io/guides/reactivity/#execution-order) is determined by the relationships between cells and their variables, not by the order of cells on the page. Multi-column notebook Get a link to share your notebook via our [online playground](https://docs.marimo.io/guides/wasm/): _Our online playground uses WebAssembly. Most but not all packages on PyPI are supported. Local files are not synchronized to our playground._ Export to static HTML[¶](#export-to-static-html "Permanent link") ----------------------------------------------------------------- Export the current view your notebook to static HTML via the notebook menu: Download as static HTML. You can also export to HTML at the command-line: `[](#__codelineno-2-1)marimo export html notebook.py -o notebook.html` Send feedback[¶](#send-feedback "Permanent link") ------------------------------------------------- The question mark icon in the panel tray opens a dialog to send anonymous feedback. We welcome any and all feedback, from the tiniest quibbles to the biggest blue-sky dreams. Send anonymous feedback with our feedback form. If you'd like your feedback to start a conversation (we'd love to talk with you!), please consider posting in our [GitHub issues](https://github.com/marimo-team/marimo/issues) or [Discord](https://marimo.io/discord?ref=docs). But if you're in a flow state and can't context switch out, the feedback form has your back. Understanding dataflow - marimo https://docs.marimo.io/guides/editor_features/dataflow/ Unlike traditional notebooks, marimo understands the relationships between cells and uses this information to keep your code and outputs consistent. These relationships are represented as a **dataflow graph**, which encodes how variables flow from one cell to another. The dataflow graph, which is inferred statically from variable definitions and references, is used to automatically run (or mark stale) cells in the correct sequence; it's also why cells can be arranged "out of order" on the page, or across columns. marimo provides several tools to help you visualize and understand the relationships it identifies between cells. Variables explorer[¶](#variables-explorer "Permanent link") ----------------------------------------------------------- The **variables explorer panel** collects marimo's understanding of the variables in your notebook into a single searchable list. To open the panel, click the **variables icon** in the **left sidebar panel**. The variable explorer shows each variable's name, type, value, where it's defined, and where it's used. Dependency explorer[¶](#dependency-explorer "Permanent link") ------------------------------------------------------------- The **dependency explorer panel** provides a _bird's-eye view_ of your notebook's dataflow, showing all cells as an interactive graph. It helps you understand high-level patterns, overall connectedness, and the broader structure of your notebook. To open the dependency explorer, click the **graph icon** in the **left sidebar panel**. You can choose between vertical or horizontal layouts. Minimap[¶](#minimap "Permanent link") ------------------------------------- The **minimap** provides a _focused slice_ of your notebook's dataflow, helping you understand the reactive context of a given cell and navigate related cells. You can toggle the minimap a _hotkey_ (`Cmd/Ctrl-Shift-i`), or select the **map icon** from the **footer toolbar**. Click a cell in the minimap to jump to it: Connections are read **left to right**: * Connections to the **left** are _direct inputs_ — cells the current cell reads from * Connections to the **right** are _direct outputs_ — cells that read from the current cell * Cells positioned left or right but not directly connected are _transitive dependencies_ — cells that influence or are influenced by the current cell, but only through one or more intermediate cells The minimap can take some getting used to, but it's an effective representation for understanding how data flows around the current cell. It's meant to show _just enough_ local context to help you debug, trace relationships, and navigate complex notebooks. For a high level overview, use the [dependency explorer](#dependency-explorer). ### Cell symbols[¶](#cell-symbols "Permanent link") The minimap uses visual indicators to show the status and connectivity of each cell: | Symbol | Meaning | | --- | --- | | | Cell uses variables from other cells | | | Cell defines variables used by other cells | | | Cell uses variables _and_ defines variables used by others | | | Cell defines variables but isn't connected to anything (safe to delete) | | | Cell doesn't define or use variables from other cells (often markdown) | | | Cell has an error | ### Reading cell connections[¶](#reading-cell-connections "Permanent link") When you select a cell, the minimap draws lines showing how data flows between cells. Since marimo cells can define multiple variables, downstream connections show all cells that reference any variable from your selected cell. | Path | Interpretation | | --- | --- | | | First cell defines variables used by the second cell. Second cell will re-run when the first runs | | | First cell uses variables from the second cell. First cell will re-run when the second runs | | | Gray cell has no connection to the blue cells above | | | Gray cell indirectly uses variables from the first cell. Whiskers indicate transitive dependencies | | | Gray cell's variables are indirectly used by the second cell. Whiskers indicate transitive dependencies | | | Cells have circular dependencies - each uses variables from the other (error) | ### Implementation notes[¶](#implementation-notes "Permanent link") The minimap was heavily inspired by [Observable's minimap](https://observablehq.com/documentation/debugging/minimap), a [thoughtfully designed](https://observablehq.com/@observablehq/introducing-visual-dataflow) dataflow visualization for their reactive JavaScript notebooks. We adapted Observable's visual design to marimo's execution model. A key difference: Observable cells are named (declaring one variable), while marimo cells can define multiple variables. This leads to asymmetric dataflow tracing. When tracing upstream, we can identify exactly which variables from a cell depends on. When tracing downstream, all variables in a dependent cell are considered affected. Our minimap also accounts for marimo's support for multi-column layouts. Reactive reference highlighting[¶](#reactive-reference-highlighting "Permanent link") ------------------------------------------------------------------------------------- marimo's **reactive reference highlighting** provides an _in-editor_ indicator when variables defined by other cells are used in the current cell. These "reactive references" are emphasized with an underline and lightly bolded text: Hover over any underlined variable and `Cmd/Ctrl-Click` to jump to its definition. This feature is currently **opt-in** and must be enabled via _Settings_ > _User Settings_ > _Display_ > _Reference highlighting_ or toggled via the command palette (`Cmd/Ctrl-K` > _Reference highlighting_). Model Context Protocol - marimo https://docs.marimo.io/guides/editor_features/mcp/ Experimental Feature MCP features are currently experimental and under active development. Features and APIs may change. marimo supports the Model Context Protocol (MCP) in two ways: as an [MCP server](https://docs.marimo.io/guides/editor_features/mcp/#mcp-server) that exposes marimo's [AI tools](https://docs.marimo.io/guides/editor_features/tools/) to external applications, and as an [MCP client](https://docs.marimo.io/guides/editor_features/mcp/#mcp-client) that connects [supported servers](https://docs.marimo.io/guides/editor_features/mcp/#supported-servers) to marimo's [chat panel](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel). Prerequisites[¶](#prerequisites "Permanent link") ------------------------------------------------- Both MCP server and client features require the MCP dependencies. Run marimo with MCP support using one of the following methods: uvuvxpip `[](#__codelineno-0-1)# run with uv in a project [](#__codelineno-0-2)uv run --with="marimo[mcp]" marimo edit notebook.py --mcp --no-token` `[](#__codelineno-1-1)# run with uvx anywhere [](#__codelineno-1-2)uvx "marimo[mcp]" edit notebook.py --mcp --no-token` `[](#__codelineno-2-1)# install with pip and a venv [](#__codelineno-2-2)pip install "marimo[mcp]" [](#__codelineno-2-3)marimo edit notebook.py --mcp --no-token` Flags The `--mcp` flag exposes an endpoint that provides access to your notebook data via the MCP server endpoint. Remove `--mcp` if you only want MCP Client features. The `--no-token` flag removes authentication, which should only be used for local development. Remove `--no-token` in production environments. MCP Server[¶](#mcp-server "Permanent link") ------------------------------------------- marimo can expose its [AI tools](https://docs.marimo.io/guides/editor_features/tools/) through an MCP server endpoint, allowing external AI applications to interact with your notebooks. ### Available tools[¶](#available-tools "Permanent link") When connected to marimo's MCP server, external applications can access all [AI tools](https://docs.marimo.io/guides/editor_features/tools/). ### Available prompts[¶](#available-prompts "Permanent link") When connected to marimo's MCP server, external applications can access the following prompts: | Prompt | Description | | --- | --- | | **active\_notebooks** | Get current active notebooks and their session IDs and file paths. Returns session IDs and file paths for all active marimo notebook sessions, along with guidance on using these IDs with marimo MCP tools. | | **errors\_summary** | Get error summaries for all active notebooks. Returns a summary of all errors across active notebooks organized by notebook and cell, including error types, messages, and affected cell IDs. | ### Connecting external applications[¶](#connecting-external-applications "Permanent link") marimo's MCP server works with any MCP-compatible application. Below are setup instructions for some commonly used applications: Connection details Replace `PORT` with your marimo server port in the examples below. If authentication is enabled, append `?access_token=YOUR_TOKEN` to the URL and replace `YOUR_TOKEN` with your marimo access token. #### Claude Code[¶](#claude-code "Permanent link") Use Claude Code's CLI to connect to marimo: `[](#__codelineno-3-1)claude mcp add --transport http marimo http://localhost:PORT/mcp/server` #### Cursor[¶](#cursor "Permanent link") Configure Cursor to connect to marimo's MCP server: `[](#__codelineno-4-1){ [](#__codelineno-4-2) "mcpServers": { [](#__codelineno-4-3) "marimo": { [](#__codelineno-4-4) "url": "http://localhost:PORT/mcp/server" [](#__codelineno-4-5) } [](#__codelineno-4-6) } [](#__codelineno-4-7)}` #### VS Code[¶](#vs-code "Permanent link") Create a .vscode/mcp.json file in your workspace and configure it to connect to marimo's MCP server: `[](#__codelineno-5-1){ [](#__codelineno-5-2) "servers": { [](#__codelineno-5-3) "marimo": { [](#__codelineno-5-4) "type": "http", [](#__codelineno-5-5) "url": "http://localhost:PORT/mcp/server" [](#__codelineno-5-6) } [](#__codelineno-5-7) } [](#__codelineno-5-8)}` MCP Client[¶](#mcp-client "Permanent link") ------------------------------------------- marimo can connect to external MCP servers to add additional tools and context to the [chat panel](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel). ### Supported servers[¶](#supported-servers "Permanent link") marimo currently supports the following MCP servers: | Server | Description | | --- | --- | | `marimo` | Provides marimo's official documentation, API reference, and code examples | | `context7` | Fetches up-to-date, version-specific documentation and code examples from official sources | ### Configuration[¶](#configuration "Permanent link") Enable MCP client servers through the marimo settings UI: Enable MCP servers in the AI settings panel. Alternatively, configure MCP servers in your marimo configuration file: marimo.toml `[](#__codelineno-6-1)[mcp] [](#__codelineno-6-2)presets = ["marimo", "context7"]` Once configured, tools from these servers will be automatically available in the [chat panel when using ask mode](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel). Custom MCP servers Support for custom MCP server configuration is not yet available. * [AI tools](https://docs.marimo.io/guides/editor_features/tools/) - Available tools exposed by the MCP server * [AI-assisted coding](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel) - Using the chat panel with MCP tools AI tools - marimo https://docs.marimo.io/guides/editor_features/tools/ Experimental Feature Tools are currently experimental and under active development. Tool definitions and availability may change. marimo exposes a set of tools that allow AI assistants to interact with your notebooks. These tools enable AI agents to read notebook content, inspect cell runtime data, access variables, handle errors, and more. These tools are available when using the [chat panel in ask mode](https://docs.marimo.io/guides/editor_features/ai_completion/#chat-panel). External AI applications can also access these tools through the [marimo MCP server](https://docs.marimo.io/guides/editor_features/mcp/#mcp-server). ### Inspection[¶](#inspection "Permanent link") | Tool | Description | | --- | --- | | **get\_active\_notebooks** | List all currently active marimo notebooks. Returns summary statistics and notebook details including names, paths, and session IDs. Start here to discover which notebooks are available. | | **get\_lightweight\_cell\_map** | Get an overview of notebook structure showing a preview of each cell. Takes a `session_id` and optional `preview_lines` parameter. Returns cell IDs, preview text, line counts, and cell types (code, markdown, SQL). | | **get\_cell\_runtime\_data** | Get detailed runtime information for a specific cell. Takes `session_id` and `cell_id` parameters. Returns full cell code, error details, runtime metadata (execution time, runtime state), and variables defined by the cell. | | **get\_cell\_outputs** | Get execution output from a specific cell. Takes `session_id` and `cell_id` parameters. Returns visual output (HTML, charts, tables, etc.) with mimetype, stdout messages, and stderr messages. | ### Data[¶](#data "Permanent link") | Tool | Description | | --- | --- | | **get\_tables\_and\_variables** | Get information about variables and data tables in a session. Takes `session_id` and `variable_names` parameters (empty list returns all). Returns table metadata (columns, primary keys, indexes, row counts) and variable values with data types. | | **get\_database\_tables** | Get database schema information with optional query filtering. Takes `session_id` and optional `query` parameter (supports regex). Returns tables with connection name, database, schema, and table details. | ### Debugging[¶](#debugging "Permanent link") | Tool | Description | | --- | --- | | **get\_notebook\_errors** | Get all errors in the notebook organized by cell. Takes `session_id` parameter. Returns error summary (total errors, affected cells) and per-cell error details (type, message, traceback). | | **lint\_notebook** | Get all marimo lint errors in the notebook. Returns lint errors as defined in the [lint rules documentation](https://docs.marimo.io/guides/lint_rules/). | ### Reference[¶](#reference "Permanent link") | Tool | Description | | --- | --- | | **get\_marimo\_rules** | Get official marimo guidelines and best practices for AI assistants. Returns the content of the marimo rules file and source URL for understanding marimo-specific conventions. | ### Editing (Agent mode only)[¶](#editing-agent-mode-only "Permanent link") | Tool | Description | | --- | --- | | **edit\_notebook** | Add, remove, or update cells in the notebook. Takes cell operations and modifications as parameters. Allows the AI agent to generate diffs that modify notebook structure and content. | | **run\_stale\_cells** | Run cells that are stale (outdated due to upstream changes). Triggers execution of affected cells to update the notebook state. | * [Model Context Protocol (MCP)](https://docs.marimo.io/guides/editor_features/mcp/) - Learn how to expose tools through the marimo MCP server * [AI-assisted coding](https://docs.marimo.io/guides/editor_features/ai_completion/) - Learn about more AI coding features Language Server - marimo https://docs.marimo.io/guides/editor_features/language_server/ Language Server Protocol (LSP)[¶](#language-server-protocol-lsp "Permanent link") --------------------------------------------------------------------------------- The marimo editor supports the Language Server Protocol (LSP) to provide enhanced code intelligence features like: * Code completion * Hover information * Go to definition * Error checking and diagnostics Installation[¶](#installation "Permanent link") ----------------------------------------------- LSP support requires additional dependencies. You can install them with: `[](#__codelineno-0-1)pip install "marimo[lsp]" [](#__codelineno-0-2)# or [](#__codelineno-0-3)uv add "marimo[lsp]" [](#__codelineno-0-4)# or [](#__codelineno-0-5)conda install -c conda-forge python-lsp-server python-lsp-ruff` This will install the necessary packages including: * [`python-lsp-server`](https://github.com/python-lsp/python-lsp-server): The core Python language server * `python-lsp-ruff`: Ruff integration for fast linting You may optionally install other `pylsp` plugins. Other Python Language Servers Support for other Python language servers is planned for future releases. Configuration[¶](#configuration "Permanent link") ------------------------------------------------- LSP support can be configured in your `pyproject.toml` file. pyproject.toml `[](#__codelineno-1-1)# Language server configuration [](#__codelineno-1-2)[tool.marimo.language_servers.pylsp] [](#__codelineno-1-3)enabled = true # Enable/disable the Python language server [](#__codelineno-1-4)enable_mypy = true # Type checking with mypy (enabled by default, if installed) [](#__codelineno-1-5)enable_ruff = true # Linting with ruff (enabled by default, if installed) [](#__codelineno-1-6)enable_flake8 = false # Linting with flake8 [](#__codelineno-1-7)enable_pydocstyle = false # Check docstring style [](#__codelineno-1-8)enable_pylint = false # Linting with pylint [](#__codelineno-1-9)enable_pyflakes = false # Syntax checking with pyflakes [](#__codelineno-1-10)[](#__codelineno-1-11)# Diagnostics configuration [](#__codelineno-1-12)[tool.marimo.diagnostics] [](#__codelineno-1-13)enabled = true # Show diagnostics in the editor` WebAssembly[¶](#webassembly "Permanent link") --------------------------------------------- Language Servers are not available when running marimo in WebAssembly. Troubleshooting[¶](#troubleshooting "Permanent link") ----------------------------------------------------- If you encounter issues with the language server: 1. Make sure you've installed the required dependencies with `pip install "marimo[lsp]"` 2. Check if the language server is enabled in your configuration 3. Try restarting the marimo server 4. Check the terminal for any error messages Agents - marimo https://docs.marimo.io/guides/editor_features/agents/ Experimental Feature Agents are currently experimental and under active development. Features and APIs may change. marimo supports external AI agents that can interact with your codebase through the [Agent Client Protocol](https://agentclientprotocol.com/) (ACP). Agents can read and write marimo notebooks, helping you with coding tasks directly from the chat panel. Supported agents[¶](#supported-agents "Permanent link") ------------------------------------------------------- marimo currently supports the following agents: ### Claude Code Agent[¶](#claude-code-agent "Permanent link") Claude Code Agent that uses your [Claude Code CLI subscription](https://docs.claude.com/en/docs/claude-code/overview) to help you with coding tasks. **Installation and login:** `[](#__codelineno-0-1)# Install [](#__codelineno-0-2)npm install -g @anthropic-ai/claude-code [](#__codelineno-0-3)# Login [](#__codelineno-0-4)claude [](#__codelineno-0-5)# Then type /login` **Connection command:** macOS/LinuxWindows `[](#__codelineno-1-1)npx stdio-to-ws "npx @zed-industries/claude-code-acp" --port 3017` `[](#__codelineno-2-1)npx stdio-to-ws "cmd /c npx @zed-industries/claude-code-acp" --port 3017` ### Gemini Agent[¶](#gemini-agent "Permanent link") Google's Gemini agent offers a limited free tier and login for more advanced features. See login and authentication instructions in the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#-authentication-options). **Connection command:** macOS/LinuxWindows `[](#__codelineno-3-1)npx stdio-to-ws "npx @google/gemini-cli --experimental-acp" --port 3019` `[](#__codelineno-4-1)npx stdio-to-ws "cmd /c npx @google/gemini-cli --experimental-acp" --port 3019` Connecting to an agent[¶](#connecting-to-an-agent "Permanent link") ------------------------------------------------------------------- 1. **Start the agent server**: Run the connection command for your chosen agent in a terminal 2. **Enable the feature flag**: Enable the feature flag under the "Lab" section in the settings menu 3. **Open the agent panel**: Click the agents icon in marimo's sidebar 4. **Select your agent**: Choose the agent from the dropdown menu 5. **Start chatting**: The agent can now read and modify your notebooks Terminal integration If you have terminal access enabled in marimo, you can run agent connection commands directly from the agent panel using the terminal button. Custom agents[¶](#custom-agents "Permanent link") ------------------------------------------------- Custom agents Support for custom agents is coming soon. This will allow you to connect to your own ACP-compatible agents Troubleshooting[¶](#troubleshooting "Permanent link") ----------------------------------------------------- **Connection issues**: Ensure the agent server is running on the correct port before connecting in marimo. **Permission requests**: Agents may request permission to read or write files. Review these carefully before approving. **Session limits**: Currently, only one session per agent is supported for optimal performance. Package management - marimo https://docs.marimo.io/guides/editor_features/package_management/ marimo supports package management for `pip`, `uv`, `poetry`, `pixi`, and `rye`. When marimo comes across a module that is not installed, you will be prompted to install it using your preferred package manager. Once the module is installed, all cells that depend on the module will be rerun. Package Installation We use some heuristic for guessing the package name in your registry (e.g. PyPI) from the module name. It is possible that the package name is different from the module name. If you encounter an error, please file an issue or help us by adding your mapping [directly to the codebase](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/module_name_to_pypi_name.py). Package reproducibility[¶](#package-reproducibility "Permanent link") --------------------------------------------------------------------- marimo is the only Python notebook that is reproducible down to the packages they use. This makes it possible to share standalone notebooks without shipping `requirements.txt` files alongside them, and guarantees your notebooks will work weeks, months, even years into the future. To learn more, see the [package reproducibility guide](https://docs.marimo.io/guides/package_management/inlining_dependencies/). Module autoreloading - marimo https://docs.marimo.io/guides/editor_features/module_autoreloading/ marimo has an advanced module autoreloader built-in, which you can enable in the [notebook settings](https://docs.marimo.io/guides/configuration/runtime_configuration/). When you make edits to Python modules that your notebook has imported, the module autoreloader will automatically mark cells that use them as stale and, optionally, automatically run them. Why autoreload? Autoreloading enables a workflow that many developers find productive: develop complex logic in Python modules, and use the marimo notebook as a DAG or main script that orchestrates your logic. Based on static analysis, the reloader only runs cells affected by your edits. The reloader is recursive, meaning that marimo tracks modifications for modules imported by your notebook's imported modules too. These two features make marimo's module autoreloader far more advanced than IPython's. Autoreloading comes in two types: 1. **autorun**: automatically re-runs cells affected by module modification. When set to autorun, marimo's reloader automatically run cells when you edit Python files. 2. **lazy**: marks cells affected by module modifications as stale, letting you know which cells need to be re-run. When set to lazy, marimo's reloader marks cells as stale when you edit Python files. Using your own editor - marimo https://docs.marimo.io/guides/editor_features/watching/ While we recommend using the [marimo editor](https://docs.marimo.io/guides/editor_features/), we understand that you may prefer to use your own. marimo provides a `--watch` flag that watches your notebook file for changes, syncing them to the marimo editor or running application. This lets you edit your notebook using an editor of your choice, like neovim, VSCode, Cursor, or PyCharm, and have the changes automatically reflected in your browser. Install watchdog for better file watching For better performance, install [watchdog](https://pypi.org/project/watchdog/). Without watchdog, marimo resorts to polling. Watch works best with autosave Verify your settings in `User Settings` > `Editor` > `Autosave` > `Autosave enabled` marimo's file format[¶](#marimos-file-format "Permanent link") -------------------------------------------------------------- File format tutorial Run `marimo tutorial fileformat` at the command line for a full guide. marimo stores notebooks as Python files. Cells are stored as functions, decorated with`@app.cell`; you can optionally give cells names in the editor UI or by editing the notebook file. `[](#__codelineno-0-1)@app.cell [](#__codelineno-0-2)def memorable_cell_name(auto, determined, references): # signature denotes cell references [](#__codelineno-0-3) computed_value = auto + determined + references [](#__codelineno-0-4) "hello!" # final statement is the visual output [](#__codelineno-0-5) return computed_value # return denotes cell definitions` Cell signature and returns Don't worry about maintaining the signatures of cells and their return values; marimo will handle this for you. ### Exposing functions and classes top-level[¶](#exposing-functions-and-classes-top-level "Permanent link") You can expose top-level functions and classes in your notebook, so that other Python modules can import them: `[](#__codelineno-1-1)from my_notebook import my_function, MyClass` Top-level functions are added to a notebook using the `@app.function` decorator, and classes with `@app.class_definition`; these appear in your notebook as cells with just a function or class definition. These functions and classes must be pure, closing over only other pure functions and classes, or imports and constants defined in an `app.setup` `with` block. Here is a complete example that you can copy/paste and run locally: `[](#__codelineno-2-1)import marimo [](#__codelineno-2-2)[](#__codelineno-2-3)app = marimo.App() [](#__codelineno-2-4)[](#__codelineno-2-5)with app.setup: [](#__codelineno-2-6) # These symbols can be used by top-level functions and classes [](#__codelineno-2-7) # (as well as by regular cells) [](#__codelineno-2-8) import numpy as np [](#__codelineno-2-9) [](#__codelineno-2-10) CONSTANT: int = 1 [](#__codelineno-2-11)[](#__codelineno-2-12)@app.function [](#__codelineno-2-13)def my_function(x: np.ndarray): [](#__codelineno-2-14) return np.mean(x) + CONSTANT [](#__codelineno-2-15)[](#__codelineno-2-16)@app.class_definition [](#__codelineno-2-17)class MyClass: [](#__codelineno-2-18) ... [](#__codelineno-2-19)[](#__codelineno-2-20)@app.cell [](#__codelineno-2-21)def _(): [](#__codelineno-2-22) my_function(np.random.randn(2, 2)) [](#__codelineno-2-23) return [](#__codelineno-2-24)[](#__codelineno-2-25)if __name__ == "__main__": [](#__codelineno-2-26) app.run()` For more details see the [guide on reusable functions and classes](https://docs.marimo.io/guides/reusing_functions/). ### Types and autocompletion[¶](#types-and-autocompletion "Permanent link") Add type hints to your variables, and marimo will carry over these type hints to cells where these variables are used. This, combined with importing modules in the setup cell (see below for an example), makes it possible for your editor to give completions on the references of your cell. For example: `[](#__codelineno-3-1)# setup cell [](#__codelineno-3-2)import numpy as np [](#__codelineno-3-3)[](#__codelineno-3-4)# cell 1 [](#__codelineno-3-5)x: np.ndarray [](#__codelineno-3-6)[](#__codelineno-3-7)# cell 2 [](#__codelineno-3-8)np.mean(x)` will be serialized as `[](#__codelineno-4-1)import marimo [](#__codelineno-4-2)[](#__codelineno-4-3)app = marimo.App() [](#__codelineno-4-4)[](#__codelineno-4-5)with app.setup: [](#__codelineno-4-6) import numpy as np [](#__codelineno-4-7)[](#__codelineno-4-8)@app.cell [](#__codelineno-4-9)def _(): [](#__codelineno-4-10) x: np.ndarray [](#__codelineno-4-11) return x, [](#__codelineno-4-12)[](#__codelineno-4-13)@app.cell [](#__codelineno-4-14)def _(x: np.ndarray): [](#__codelineno-4-15) np.mean(x) [](#__codelineno-4-16)[](#__codelineno-4-17)if __name__ == "__main__": [](#__codelineno-4-18) app.run()` ### As markdown[¶](#as-markdown "Permanent link") Markdown File format tutorial Run `marimo tutorial markdown-format` at the command line for a full guide. marimo notebooks can also be stored as Markdown files. This is a good option for prose heavy text, and can be easy to navigate and edit in external editors. To convert a marimo notebook to markdown, use `[](#__codelineno-5-1)marimo export md notebook.py -o notebook.md` at the command-line, or rename your file to have an `.md` extension in the notebook editor. marimo conforms to standard markdown document format, and will render most places like Github. Metadata in this file format is saved in the frontmatter, which marimo may use for information like [sandboxing](https://docs.marimo.io/guides/package_management/inlining_dependencies/), and the marimo version. All other fields are kept, but ignored. For execution, marimo extracts code fences that contain `marimo` in braces. For instance `python {marimo}`, `{marimo}` or `{.marimo .python}`. The marimo editor uses `python {.marimo}` which is Pandoc compatible, and correctly processed by text highlighters. ` [](#__codelineno-6-1)--- [](#__codelineno-6-2)title: My Notebook [](#__codelineno-6-3)marimo-version: 0.0.0 [](#__codelineno-6-4)description: A notebook with a description [](#__codelineno-6-5)--- [](#__codelineno-6-6)[](#__codelineno-6-7)# Just a notebook [](#__codelineno-6-8)[](#__codelineno-6-9)```python {.marimo} [](#__codelineno-6-10)print("Hello World!") [](#__codelineno-6-11)``` ` marimo's markdown format can be used with a [`mkdocs plugin`](https://github.com/marimo-team/mkdocs-marimo) and [`Quarto`](https://github.com/marimo-team/quarto-marimo). Note that the markdown format is not as fully featured as the Python format. Reactive tests will not work, markdown notebooks cannot be imported or used as a library, and they cannot be run as scripts. Watching for changes to your notebook[¶](#watching-for-changes-to-your-notebook "Permanent link") ------------------------------------------------------------------------------------------------- ### `marimo edit --watch`[¶](#marimo-edit-watch "Permanent link") When you run `marimo edit` with the `--watch` flag, the marimo server will open your notebook in the browser and watch the underlying notebook file for changes. When you make changes to the notebook file, they will be streamed to the marimo editor in the browser. By default, synced code will not be executed automatically, with cells marked as stale instead. Run all stale cells with the marimo editor's "Run" button, or the [`runStale` hotkey](https://docs.marimo.io/guides/editor_features/hotkeys/), to see the new outputs. If you want to run all affected cells automatically when you save, change the `runtime` config in your `pyproject.toml` file. `[](#__codelineno-7-1)[tool.marimo.runtime] [](#__codelineno-7-2)watcher_on_save = "autorun"` ### `marimo run --watch`[¶](#marimo-run-watch "Permanent link") When you run `marimo run` with the `--watch` flag, whenever the file watcher detects a change to the notebook file, the application will be refreshed. The browser will trigger a page refresh to ensure your notebook starts from a fresh state. Watching for changes to other modules[¶](#watching-for-changes-to-other-modules "Permanent link") ------------------------------------------------------------------------------------------------- marimo can also watch for changes to Python modules that your notebook imports, letting you edit auxiliary Python files in your own editor as well. Learn how to enable this feature in our [Module Autoreloading Guide](https://docs.marimo.io/guides/editor_features/module_autoreloading/) Watching for data changes[¶](#watching-for-data-changes "Permanent link") ------------------------------------------------------------------------- Data file watching now supported! marimo now supports watching data files and automatically refreshing cells that depend on them using `mo.watch.file()` and `mo.watch.directory()`. Learn more in the [watch API documentation](https://docs.marimo.io/api/watch/). Hot-reloading WebAssembly notebooks[¶](#hot-reloading-webassembly-notebooks "Permanent link") --------------------------------------------------------------------------------------------- Follow these steps to develop a notebook using your own editor while previewing it as a [WebAssembly notebook](https://docs.marimo.io/guides/wasm/) in the browser. This lets you take advantage of local development tools while seeing the notebook as it appears when deployed as a WebAssembly notebook. `[](#__codelineno-8-1)# in one terminal, start a watched edit (or run) session [](#__codelineno-8-2)marimo edit notebook.py --watch [](#__codelineno-8-3)[](#__codelineno-8-4)# in another terminal [](#__codelineno-8-5)marimo export html-wasm notebook.py -o output_dir --watch [](#__codelineno-8-6)[](#__codelineno-8-7)# in a third terminal, serve the WASM application [](#__codelineno-8-8)cd path/to/output_dir [](#__codelineno-8-9)python -m http.server # or a server that watches for changes` Hotkeys - marimo https://docs.marimo.io/guides/editor_features/hotkeys/ If you'd like to override the default hotkeys, you can do so in the hotkeys menu (`Ctrl/Cmd-Shift-h`), or modifying your `marimo.toml`. You can find a list of available hotkeys below: | Hotkey | | --- | | `cell.aiCompletion` | | `cell.cellActions` | | `cell.complete` | | `cell.createAbove` | | `cell.createBelow` | | `cell.delete` | | `cell.findAndReplace` | | `cell.focusDown` | | `cell.focusUp` | | `cell.fold` | | `cell.foldAll` | | `cell.format` | | `cell.goToDefinition` | | `cell.hideCode` | | `cell.moveUp` | | `cell.moveDown` | | `cell.moveLeft` | | `cell.moveRight` | | `cell.redo` | | `cell.run` | | `cell.runAndNewAbove` | | `cell.runAndNewBelow` | | `cell.selectNextOccurrence` | | `cell.sendToBottom` | | `cell.sendToTop` | | `cell.splitCell` | | `cell.undo` | | `cell.unfold` | | `cell.unfoldAll` | | `cell.viewAsMarkdown` | | `completion.moveDown` | | `completion.moveUp` | | `global.commandPalette` | | `global.focusBottom` | | `global.focusTop` | | `global.foldCode` | | `global.formatAll` | | `global.hideCode` | | `global.interrupt` | | `global.runStale` | | `global.save` | | `global.showHelp` | | `global.toggleLanguage` | | [`global.toggleMinimap`](https://docs.marimo.io/guides/editor_features/dataflow/#minimap) | | `global.toggleTerminal` | | `global.toggleSidebar` | | `global.unfoldCode` | | `markdown.blockquote` | | `markdown.bold` | | `markdown.code` | | `markdown.italic` | | `markdown.link` | | `markdown.orderedList` | | `markdown.unorderedList` | Run notebooks as apps - marimo https://docs.marimo.io/guides/apps/ Run as an app[¶](#run-as-an-app "Permanent link") ------------------------------------------------- The marimo CLI lets you run any notebook as an app: `marimo run` lays out the notebook as an app and starts a web server that hosts the resulting app. By default, apps are laid out as a concatenation of their outputs, with code hidden. You can customize the layout using marimo's built-in drag-and-drop grid editor; you can also choose to include code in the app view. CLI[¶](#cli "Permanent link") ----------------------------- Run marimo notebooks as apps with View the [CLI documentation](https://docs.marimo.io/cli/#marimo-run) for more details. Layout[¶](#layout "Permanent link") ----------------------------------- While editing a notebook with `marimo edit`, you can preview the notebook as an app by clicking the preview button in the bottom-right of the editor. (You can also use the command palette.) `layouts` folder marimo saves metadata about your constructed layout in a `layouts` folder; make sure to include this folder when sharing or deploying your notebook so that others can reconstruct your layout. Include this folder in version control. ### Vertical layout[¶](#vertical-layout "Permanent link") The default layout is the vertical layout: cell outputs are concatenated vertically and code is hidden. When combined with marimo's [built-in functions for laying out outputs](https://docs.marimo.io/api/layouts/), as well as its configurable app widths (configure via the notebook settings menu), the vertical layout can successfully support a wide breadth of application user interfaces. ### Grid layout[¶](#grid-layout "Permanent link") If you prefer a drag-and-drop experience over [programmatic layout](https://docs.marimo.io/api/layouts/), consider using marimo's grid editor for making your apps: with this editor, you simply drag outputs onto a grid to arrange them on the page. Enable the grid editor in the app preview, via a dropdown: ### Slides layout[¶](#slides-layout "Permanent link") If you prefer a slideshow-like experience, you can use the slides layout. Enable the slides layout in the app preview, via the same dropdown as above. Unlike the grid layout, the slides are much less customizable: * The order of the slides is determined by the order of the cells in the notebook. * The slides do not support drag-and-drop rearrangement or resizing. * All outputs are shown and all code is hidden. If you need more control over the layout, please file an issue on [GitHub](https://github.com/marimo-team/marimo/issues), so we can properly prioritize this feature. Testing notebooks - marimo https://docs.marimo.io/guides/testing/ Because marimo notebooks are stored as Python, test them like any other Python program. | Guide | Description | | --- | --- | | [pytest](https://docs.marimo.io/guides/testing/pytest/) | Include unit tests in notebooks, or implement entire tests as notebooks | | [doctest](https://docs.marimo.io/guides/testing/doctest/) | Test code snippets in docstrings using doctest | Run notebooks as scripts - marimo https://docs.marimo.io/guides/scripts/ Run as a script[¶](#run-as-a-script "Permanent link") ----------------------------------------------------- You can run marimo notebooks as scripts at the command line, just like any other Python script. For example, `[](#__codelineno-0-1)python my_marimo_notebook.py` Running a notebook as a script is useful when your notebook has side-effects, like writing to disk. Print statements and other console outputs will show up in your terminal. Check before running Before running a notebook as a script, you can use marimo's linter to check for issues that might prevent execution: `[](#__codelineno-1-1)marimo check my_marimo_notebook.py` See the [Lint Rules](https://docs.marimo.io/guides/lint_rules/) guide for more information about marimo's linting system. Saving notebook outputs To run as a script while also saving HTML of the notebook outputs, use `[](#__codelineno-2-1)marimo export html notebook.py -o notebook.html` You can also pass command-line arguments to your notebook during export. Separate these args from the command with two dashes: `[](#__codelineno-3-1)marimo export html notebook.py -o notebook.html -- -arg value` Exporting to other formats, such as ipynb, is also possible: `[](#__codelineno-4-1)marimo export ipynb notebook.py -o notebook.ipynb -- -arg value` Command-line arguments[¶](#command-line-arguments "Permanent link") ------------------------------------------------------------------- When run as a script, you can access your notebook's command-line arguments through `sys.argv`, just like any other Python program. This also means you can declare your notebook's command-line arguments using Python libraries like [`argparse`](https://docs.python.org/3/library/argparse.html) and [`simple-parsing`](https://github.com/lebrice/SimpleParsing). These examples shows how to conditionally assign values to variables based on command-line arguments when running as a script, and use default values when running as a notebook. ### argparse[¶](#argparse "Permanent link") Source code for `examples/running_as_a_script/sharing_arguments.py` Tip: paste this code into an empty cell, and the marimo editor will create cells for you ``import marimo __generated_with = "0.17.2" app = marimo.App(width="medium") @app.cell def _(): import marimo as mo return (mo,) @app.cell def _(): import argparse return (argparse,) @app.cell(hide_code=True) def _(mo): mo.md(""" This notebook shows how to parametrize a notebook with optional command-line arguments. Run the notebook with ```bash marimo edit sharing_arguments.py ``` or ```bash marimo edit sharing_arguments.py -- -learning_rate=1e-3 ``` (Note the `--` separating the filename from the arguments.) or ```bash python sharing_arguments.py -learning_rate=1e-3 ``` See help for the notebook's arguments with ```python python sharing_arguments.py --help ``` """) return @app.cell def _(mo): default = mo.ui.number(1000, step=100) default return (default,) @app.cell def _(argparse, default): parser = argparse.ArgumentParser() parser.add_argument("-iterations", default=default.value) args = parser.parse_args() print(args.iterations) return if __name__ == "__main__": app.run()`` ### simple-parsing[¶](#simple-parsing "Permanent link") Source code for `examples/running_as_a_script/with_simple_parsing.py` Tip: paste this code into an empty cell, and the marimo editor will create cells for you `# /// script # requires-python = ">=3.12" # dependencies = [ # "marimo", # "simple-parsing==0.1.7", # ] # /// import marimo __generated_with = "0.15.5" app = marimo.App(width="medium") @app.cell def _(): import marimo as mo return (mo,) @app.cell def _(): import simple_parsing return @app.cell def _(): from dataclasses import dataclass from simple_parsing import ArgumentParser parser = ArgumentParser() parser.add_argument("--foo", type=int, default=123, help="foo help") @dataclass class Options: """Help string for this group of command-line arguments.""" log_dir: str # Help string for a required str argument learning_rate: float = 1e-4 # Help string for a float argument parser.add_arguments(Options, dest="options") return Options, parser @app.cell def _(Options, mo, parser): from dataclasses import fields def parse_args(): if mo.running_in_notebook(): # set default values for the command-line arguments when running as a notebook return "foo default", Options("logs/", 1e-4) else: args = parser.parse_args() return args.foo, args.options return (parse_args,) @app.cell def _(parse_args): foo, options = parse_args() print(foo, options) return if __name__ == "__main__": app.run()` pytest - marimo https://docs.marimo.io/guides/testing/pytest/ Testing with pytest[¶](#testing-with-pytest "Permanent link") ------------------------------------------------------------- Testing in notebook[¶](#testing-in-notebook "Permanent link") ------------------------------------------------------------- By default, marimo discovers and executes tests inside your notebook. When the optional `pytest` dependency is present, marimo runs `pytest` on cells that consist exclusively of test code - i.e. functions whose names start with `test_` or classes whose names start with `Test`. If a cell mixes in anything else (helper functions, constants, variables, imports, etc.), that cell is skipped by the test runner (we recommend you move helpers to another cell). For example, Reactive tests can be disabled You can disable this behavior with the `runtime.reactive_test` option in the configuration file. Testing at the command-line[¶](#testing-at-the-command-line "Permanent link") ----------------------------------------------------------------------------- Since marimo notebooks are Python programs, you can test them using [`pytest`](https://docs.pytest.org/en/stable/), a popular testing framework for Python. For example, runs and tests all notebook cells whose names start with `test_`, or cells that contain only `test_` functions and `Test` classes (just like in notebook tests). Naming cells Name a cell by giving its function a name in the notebook file, or using the cell action menu in the notebook editor. Use marimo notebooks just like normal pytest tests Include test notebooks (notebooks whose names start with `test_`) in your standard test suite, and `pytest` will discover them automatically. In addition, you can write self-contained notebooks that contain their own unit tests, and run `pytest` on them directly (`pytest my_notebook.py`). Example[¶](#example "Permanent link") ------------------------------------- Running `pytest` on `[](#__codelineno-2-1)# content of test_notebook.py [](#__codelineno-2-2)import marimo [](#__codelineno-2-3)[](#__codelineno-2-4)__generated_with = "0.10.6" [](#__codelineno-2-5)app = marimo.App() [](#__codelineno-2-6) [](#__codelineno-2-7)[](#__codelineno-2-8)@app.cell [](#__codelineno-2-9)def _(): [](#__codelineno-2-10) def inc(x): [](#__codelineno-2-11) return x + 1 [](#__codelineno-2-12) return (inc,) [](#__codelineno-2-13) [](#__codelineno-2-14)[](#__codelineno-2-15)@app.cell [](#__codelineno-2-16)def test_fails(inc): [](#__codelineno-2-17) assert inc(3) == 5, "This test fails" [](#__codelineno-2-18) [](#__codelineno-2-19)[](#__codelineno-2-20)@app.cell [](#__codelineno-2-21)def test_sanity(inc): [](#__codelineno-2-22) assert inc(3) == 4, "This test passes" [](#__codelineno-2-23)[](#__codelineno-2-24)@app.cell [](#__codelineno-2-25)def collection_of_tests(inc, pytest): [](#__codelineno-2-26) @pytest.mark.parametrize(("x", "y"), [(3, 4), (4, 5)]) [](#__codelineno-2-27) def test_answer(x, y): [](#__codelineno-2-28) assert inc(x) == y, "These tests should pass." [](#__codelineno-2-29)[](#__codelineno-2-30)@app.cell [](#__codelineno-2-31)def imports(): [](#__codelineno-2-32) import pytest [](#__codelineno-2-33) return pytest` prints `[](#__codelineno-3-1)============================= test session starts ============================== [](#__codelineno-3-2)platform linux -- Python 3.12.9, pytest-8.3.5, pluggy-1.5.0 [](#__codelineno-3-3)rootdir: /notebooks [](#__codelineno-3-4)configfile: pyproject.toml [](#__codelineno-3-5)collected 4 items [](#__codelineno-3-6)[](#__codelineno-3-7)test_notebook.py::test_fails FAILED [ 25%] [](#__codelineno-3-8)test_notebook.py::test_sanity PASSED [ 50%] [](#__codelineno-3-9)test_notebook.py::MarimoTestBlock_0::test_parameterized[3-4] PASSED [ 75%] [](#__codelineno-3-10)test_notebook.py::MarimoTestBlock_0::test_parameterized[4-5] PASSED [100%] [](#__codelineno-3-11)[](#__codelineno-3-12)=================================== FAILURES =================================== [](#__codelineno-3-13)__________________________________ test_fails __________________________________ [](#__codelineno-3-14) [](#__codelineno-3-15) # content of test_notebook.py [](#__codelineno-3-16) import marimo [](#__codelineno-3-17) [](#__codelineno-3-18) __generated_with = "0.10.6" [](#__codelineno-3-19) app = marimo.App() [](#__codelineno-3-20) [](#__codelineno-3-21) [](#__codelineno-3-22) @app.cell [](#__codelineno-3-23) def _(): [](#__codelineno-3-24) def inc(x): [](#__codelineno-3-25) return x + 1 [](#__codelineno-3-26) return (inc,) [](#__codelineno-3-27) [](#__codelineno-3-28) [](#__codelineno-3-29) @app.cell [](#__codelineno-3-30) def test_fails(inc): [](#__codelineno-3-31)> assert inc(3) == 5, "This test fails" [](#__codelineno-3-32)E AssertionError: This test fails [](#__codelineno-3-33)E assert 4 == 5 [](#__codelineno-3-34)E + where 4 = (3) [](#__codelineno-3-35)[](#__codelineno-3-36)test_notebook.py:17: AssertionError [](#__codelineno-3-37)=========================== short test summary info ============================ [](#__codelineno-3-38)FAILED test_notebook.py::test_fails - AssertionError: This test fails [](#__codelineno-3-39)========================= 1 failed, 3 passed in 0.82s ==========================` Reuse functions and classes - marimo https://docs.marimo.io/guides/reusing_functions/ Importing functions and classes defined in notebooks[¶](#importing-functions-and-classes-defined-in-notebooks "Permanent link") ------------------------------------------------------------------------------------------------------------------------------- You can import top-level functions and classes defined in a marimo notebook into other Python scripts or notebooks using normal Python syntax, as long as your definitions satisfy the simple criteria described on this page. This makes your notebook code reusable, testable, and easier to edit in text editors of your choice. Overview[¶](#overview "Permanent link") --------------------------------------- For a function or class to be saved at the top level of the notebook file, it must meet the following **criteria**: 1. The cell must define just a single function or class. 2. The defined function or class can only refer to symbols defined in the [setup cell](#1-create-a-setup-cell), or to other top-level symbols. ### Example[¶](#example "Permanent link") In another script or notebook `[](#__codelineno-1-1)from my_notebook import my_utility_function, DataProcessor` Creating a top-level function or class[¶](#creating-a-top-level-function-or-class "Permanent link") --------------------------------------------------------------------------------------------------- ### 1\. Create a setup cell[¶](#1-create-a-setup-cell "Permanent link") First, add a **setup cell** to your notebook for imports that your functions or classes will need: To add a setup cell in the editor, open the notebook menu and select "Add setup cell". (The setup cell is guaranteed to run before other cells.) ### 2\. Define your function[¶](#2-define-your-function "Permanent link") Define a single function in a cell. If the [criteria](#overview) for top-level functions are met, a marker in the bottom right will indicate that it is a reusable function. Note Functions can only reference symbols defined in the setup cell. If a function cannot be serialized top-level, the marker in the bottom right will provide a description why. Under the hood, marimo decorates top-level functions with `@app.function`, which you can use to define your own top-level functions if you are editing a notebook file directly. Top-level classes are decorated with `@app.class_definition`. ### 3\. Import into other Python files[¶](#3-import-into-other-python-files "Permanent link") Now you can import your function in other notebooks or Python scripts: `[](#__codelineno-4-1)# In another_script.py [](#__codelineno-4-2)from my_notebook import calculate_statistics [](#__codelineno-4-3)[](#__codelineno-4-4)data = [1, 2, 3, 4, 5] [](#__codelineno-4-5)stats = calculate_statistics(data) [](#__codelineno-4-6)print(stats)` Best practices[¶](#best-practices "Permanent link") --------------------------------------------------- * Use setup cells for widely used imports * Keep function dependencies limited to setup-cell references, or other top-level declarations * Use descriptive names for your functions * Add docstrings to document your functions' behavior Tip Top-level symbols can reference other top-level symbols. Limitations[¶](#limitations "Permanent link") --------------------------------------------- * Functions cannot depend on variables defined in regular cells * Like other cells, cyclic dependencies between functions are not allowed * Functions cannot be exported from notebooks in [marimo's markdown format](https://docs.marimo.io/guides/editor_features/watching/#as-markdown). Learn more[¶](#learn-more "Permanent link") ------------------------------------------- For more on marimo's file format, check out our [documentation on using your own editor](https://docs.marimo.io/guides/editor_features/watching/) or view our [file format tutorial](https://links.marimo.app/tutorial-fileformat). doctest - marimo https://docs.marimo.io/guides/testing/doctest/ Tip: paste this code into an empty cell, and the marimo editor will create cells for you `import marimo __generated_with = "0.15.5" app = marimo.App(width="medium") @app.cell def _(): import marimo as mo return (mo,) @app.function def euclid_mcd(a: int, b: int) -> int: """Return the MCD between positive a, b. >>> euclid_mcd(42, 24) 6 >>> euclid_mcd(24, 42) 6 >>> euclid_mcd(42, 42) 42 """ assert a > 0 assert b > 0 if a < b: a, b = b, a if (a != b): r = a - b return euclid_mcd(b, r) return a @app.cell def _(mo): # Include a reference to each function to test euclid_mcd import doctest failures, success = doctest.testmod(verbose=True) mo.md(f"Success: {success}, Failures: {failures}") return if __name__ == "__main__": app.run()` Export to other formats - marimo https://docs.marimo.io/guides/exporting/ Exporting to HTML and other formats[¶](#exporting-to-html-and-other-formats "Permanent link") --------------------------------------------------------------------------------------------- Export marimo notebooks to other file formats at the command line using Export to static HTML[¶](#export-to-static-html "Permanent link") ----------------------------------------------------------------- ### Export from a running notebook[¶](#export-from-a-running-notebook "Permanent link") Export the current view your notebook to static HTML via the notebook menu: Download as static HTML. Additionally, you can configure individual notebooks to automatically save as HTML through the notebook menu. These automatic snapshots are saved to a folder called `__marimo__` in the notebook directory. ### Export from the command line[¶](#export-from-the-command-line "Permanent link") Export to HTML at the command line: `[](#__codelineno-1-1)marimo export html notebook.py -o notebook.html` or watch the notebook for changes and automatically export to HTML: `[](#__codelineno-2-1)marimo export html notebook.py -o notebook.html --watch` When you export from the command line, marimo runs your notebook to produce its visual outputs before saving as HTML. Note If any cells error during the export process, the status code will be non-zero. However, the export result may still be generated, with the error included in the output. Errors can be ignored by appending `|| true` to the command, e.g. `marimo export html notebook.py || true`. ### Pre-render HTML exports[¶](#pre-render-html-exports "Permanent link") Static marimo exports execute Javascript to render the notebook source code as HTML at browser runtime. If you would like to directly serve the HTML representation of your notebook, you can run the following post-processing script and serve the resulting file instead. `[](#__codelineno-3-1)# /// script [](#__codelineno-3-2)# requires-python = ">=3.9" [](#__codelineno-3-3)# dependencies = [ [](#__codelineno-3-4)# "playwright", [](#__codelineno-3-5)# ] [](#__codelineno-3-6)# /// [](#__codelineno-3-7)[](#__codelineno-3-8)import os [](#__codelineno-3-9)import subprocess [](#__codelineno-3-10)from playwright.sync_api import sync_playwright [](#__codelineno-3-11)[](#__codelineno-3-12)input_file = "input.html" [](#__codelineno-3-13)output_file = "output.html" [](#__codelineno-3-14)[](#__codelineno-3-15)subprocess.run(["playwright", "install", "chromium-headless-shell"], check=True) [](#__codelineno-3-16)[](#__codelineno-3-17)with sync_playwright() as p: [](#__codelineno-3-18) with p.chromium.launch(headless=True) as browser: [](#__codelineno-3-19) page = browser.new_page() [](#__codelineno-3-20) page.goto( [](#__codelineno-3-21) f"file:///{os.path.abspath(input_file)}", [](#__codelineno-3-22) wait_until="networkidle", [](#__codelineno-3-23) ) [](#__codelineno-3-24) with open(output_file, "w", encoding="utf-8") as f: [](#__codelineno-3-25) f.write(page.content())` Export to a Python script[¶](#export-to-a-python-script "Permanent link") ------------------------------------------------------------------------- Export to a flat Python script in topological order, so the cells adhere to their dependency graph. `[](#__codelineno-4-1)marimo export script notebook.py -o notebook.script.py` Top-level await not supported Exporting to a flat Python script does not support top-level await. If you have top-level await in your notebook, you can still execute the notebook as a script with `python notebook.py`. Export to markdown[¶](#export-to-markdown "Permanent link") ----------------------------------------------------------- Export to markdown notebook in top to bottom order, so the cells are in the order as they appear in the notebook. `[](#__codelineno-5-1)marimo export md notebook.py -o notebook.md` This can be useful to plug into other tools that read markdown, such as [Quarto](https://quarto.org/) or [MyST](https://myst-parser.readthedocs.io/). marimo can directly open markdown files as notebooks Learn more with `marimo tutorial markdown-format` at the command line. You can also convert the markdown back to a marimo notebook: `[](#__codelineno-6-1)marimo convert notebook.md > notebook.py` Export to Jupyter notebook[¶](#export-to-jupyter-notebook "Permanent link") --------------------------------------------------------------------------- Export to Jupyter notebook in topological order, so the cells adhere to their dependency graph. `[](#__codelineno-7-1)marimo export ipynb notebook.py -o notebook.ipynb` Exporting to PDF, slides, or rst[¶](#exporting-to-pdf-slides-or-rst "Permanent link") ------------------------------------------------------------------------------------- The marimo [Quarto](https://www.github.com/marimo-team/quarto-marimo) plugin enables exporting to PDF and other formats with Pandoc. See this [publishing](https://docs.marimo.io/guides/publishing/quarto/) for more details. However, if you export to a Jupyter notebook, you can leverage various other Jupyter ecosystem tools. For PDFs, you will need to have [Pandoc](https://nbconvert.readthedocs.io/en/latest/install.html#installing-pandoc) and [Tex](https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex) installed. The examples below use `uvx`, which you can obtain by [installing `uv`](https://docs.astral.sh/uv/getting-started/installation/). `[](#__codelineno-8-1)NOTEBOOK=notebook.ipynb [](#__codelineno-8-2)[](#__codelineno-8-3)# Convert to PDF using nbconvert [](#__codelineno-8-4)uvx --with nbconvert --from jupyter-core jupyter nbconvert --to pdf $NOTEBOOK [](#__codelineno-8-5)[](#__codelineno-8-6)# Convert to web PDF [](#__codelineno-8-7)uvx --with "nbconvert[webpdf]" --from jupyter-core jupyter nbconvert --to webpdf $NOTEBOOK --allow-chromium-download [](#__codelineno-8-8)[](#__codelineno-8-9)# Convert to slides [](#__codelineno-8-10)uvx --with nbconvert --from jupyter-core jupyter nbconvert --to slides $NOTEBOOK [](#__codelineno-8-11)[](#__codelineno-8-12)# Convert to rst with nbconvert [](#__codelineno-8-13)uvx --with nbconvert --from jupyter-core jupyter nbconvert --to rst $NOTEBOOK [](#__codelineno-8-14)[](#__codelineno-8-15)# Generate PNG/PDF of specific cells using nbconvert [](#__codelineno-8-16)uvx --with nbconvert --with jupyter --from jupyter-core jupyter nbconvert --to pdf --execute --stdout $NOTEBOOK \ [](#__codelineno-8-17) --TemplateExporter.exclude_input=True [](#__codelineno-8-18)[](#__codelineno-8-19)# Use nbconvert programmatically for more control [](#__codelineno-8-20)uv run --with nbconvert python -c " [](#__codelineno-8-21)from nbconvert import PDFExporter [](#__codelineno-8-22)import nbformat [](#__codelineno-8-23)nb = nbformat.read('$NOTEBOOK', as_version=4) [](#__codelineno-8-24)pdf_exporter = PDFExporter() [](#__codelineno-8-25)pdf_data, resources = pdf_exporter.from_notebook_node(nb) [](#__codelineno-8-26)with open('notebook.pdf', 'wb') as f: [](#__codelineno-8-27) f.write(pdf_data) [](#__codelineno-8-28)"` You can also use other tools that work with Jupyter notebooks: * [Quarto](https://quarto.org/) - Create beautiful documents, websites, presentations * [nbgrader](https://nbgrader.readthedocs.io/) - Grade notebook assignments Export to WASM-powered HTML[¶](#export-to-wasm-powered-html "Permanent link") ----------------------------------------------------------------------------- Export your notebook to a self-contained HTML file that runs using [WebAssembly](https://docs.marimo.io/guides/wasm/): `[](#__codelineno-9-1)# export as readonly, with code locked [](#__codelineno-9-2)marimo export html-wasm notebook.py -o output_dir --mode run [](#__codelineno-9-3)# export as an editable notebook [](#__codelineno-9-4)marimo export html-wasm notebook.py -o output_dir --mode edit` The exported HTML file will run your notebook using WebAssembly, making it completely self-contained and executable in the browser. This means users can interact with your notebook without needing Python or marimo installed. Options: * `--mode`: Choose between `run` (read-only) or `edit` (allows editing) * `--output`: Directory to save the HTML and required assets * `--show-code/--no-show-code`: Whether to initially show or hide the code in the notebook * `--watch/--no-watch`: Watch the notebook for changes and automatically export * `--include-cloudflare`: Write configuration files necessary for deploying to Cloudflare Note that WebAssembly notebooks have [limitations](https://docs.marimo.io/guides/wasm/#limitations); in particular, [many but not all packages work](https://docs.marimo.io/guides/wasm/#packages). Note The exported file must be served over HTTP to function correctly - it cannot be opened directly from the filesystem (`file://`). Your server must also serve the assets in the `assets` directory, next to the HTML file. For a simpler publishing experience, publish to [GitHub Pages](https://docs.marimo.io/guides/publishing/github_pages/), [Cloudflare](https://docs.marimo.io/guides/publishing/cloudflare/) or use the [online playground](https://docs.marimo.io/guides/publishing/playground/). Deploying to Cloudflare You can include `--include-cloudflare` for deploying to Cloudflare. For example: `[](#__codelineno-10-1)marimo export html-wasm notebook.py -o my_app/dist --include-cloudflare` To run locally, run: To deploy to Cloudflare, run: ### Testing the export[¶](#testing-the-export "Permanent link") You can test the export by running the following command in the directory containing your notebook: `[](#__codelineno-13-1)cd path/to/output_dir [](#__codelineno-13-2)python -m http.server` ### Including data files[¶](#including-data-files "Permanent link") See the docs for [mo.notebook\_location](https://docs.marimo.io/api/miscellaneous/#marimo.notebook_location " marimo.notebook_location") to learn how to include data files in exported WASM HTML notebooks. ### Publishing to GitHub Pages[¶](#publishing-to-github-pages "Permanent link") After exporting your notebook to WASM HTML, you can publish it to [GitHub Pages](https://pages.github.com/) for free. See our [guide on GitHub Pages](https://docs.marimo.io/guides/publishing/github_pages/) to learn more. ### Exporting multiple notebooks[¶](#exporting-multiple-notebooks "Permanent link") In order to export multiple notebooks under the same folder, you can use the following snippet: `[](#__codelineno-14-1)files=("batch_and_form.py" "data_explorer.py") [](#__codelineno-14-2)[](#__codelineno-14-3)for file in "${files[@]}"; do [](#__codelineno-14-4) without_extension="${file%.*}" [](#__codelineno-14-5) marimo export html-wasm "$file" -o site/"$without_extension".html --mode run [](#__codelineno-14-6)done` Optionally, you can create an `index.html` file in the public directory: `[](#__codelineno-15-1)echo "" >> site/index.html` 🏝️ Embed marimo outputs in HTML using Islands[¶](#embed-marimo-outputs-in-html-using-islands "Permanent link") --------------------------------------------------------------------------------------------------------------- Preview Islands are an early feature. While the API likely won't change, there are some improvements we'd like to make before we consider them stable. Please let us know on [GitHub](https://github.com/marimo-team/marimo/issues) if you run into any issues or have any feedback! marimo islands are a way to embed marimo outputs and/or python code in your HTML that will become interactive when the page is loaded. This is useful for creating interactive blog posts, tutorials, and educational materials, all powered by marimo's reactive runtime. Check out an [example island-powered document](https://docs.marimo.io/guides/island_example/). ### Generating islands[¶](#generating-islands "Permanent link") Use `MarimoIslandGenerator` to generate HTML for islands Example From code blocksFrom notebook files `[](#__codelineno-16-1)import asyncio [](#__codelineno-16-2)import sys [](#__codelineno-16-3)from marimo import MarimoIslandGenerator [](#__codelineno-16-4)[](#__codelineno-16-5)if sys.platform == 'win32': [](#__codelineno-16-6) asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) [](#__codelineno-16-7)[](#__codelineno-16-8)async def main(): [](#__codelineno-16-9) generator = MarimoIslandGenerator() [](#__codelineno-16-10) block1 = generator.add_code("import marimo as mo") [](#__codelineno-16-11) block2 = generator.add_code("mo.md('Hello, islands!')") [](#__codelineno-16-12) [](#__codelineno-16-13) # Build the app [](#__codelineno-16-14) app = await generator.build() [](#__codelineno-16-15) [](#__codelineno-16-16) # Render the app [](#__codelineno-16-17) output = f""" [](#__codelineno-16-18) [](#__codelineno-16-19) [](#__codelineno-16-20) {generator.render_head()} [](#__codelineno-16-21) [](#__codelineno-16-22) [](#__codelineno-16-23) {block1.render(display_output=False)} [](#__codelineno-16-24) {block2.render()} [](#__codelineno-16-25) [](#__codelineno-16-26) [](#__codelineno-16-27) """ [](#__codelineno-16-28) print(output) [](#__codelineno-16-29) # Save the HTML to a file [](#__codelineno-16-30) output_file = "output.html" [](#__codelineno-16-31) with open(output_file, "w", encoding="utf-8") as f: [](#__codelineno-16-32) f.write(output) [](#__codelineno-16-33)[](#__codelineno-16-34)if __name__ == '__main__': [](#__codelineno-16-35) asyncio.run(main())` `[](#__codelineno-17-1)from marimo import MarimoIslandGenerator [](#__codelineno-17-2)[](#__codelineno-17-3)# Create the generator from file [](#__codelineno-17-4)generator = MarimoIslandGenerator.from_file("./.py", display_code=False) [](#__codelineno-17-5)[](#__codelineno-17-6)# Generate and print the HTML without building [](#__codelineno-17-7)# This will still work for basic rendering, though without running the cells [](#__codelineno-17-8)html = generator.render_html(include_init_island=False) [](#__codelineno-17-9)print(html) [](#__codelineno-17-10)# Save the HTML to a file [](#__codelineno-17-11)output_file = "output.html" [](#__codelineno-17-12)with open(output_file, "w", encoding="utf-8") as f: [](#__codelineno-17-13) f.write(html)` Any relevant `.html` that gets generated can be run through the [`development.md`](https://github.com/marimo-team/marimo/blob/main/frontend/islands/development.md) file instructions. ### Islands in action[¶](#islands-in-action "Permanent link") Advanced topic! Islands are an advanced concept that is meant to be a building block for creating integrations with existing tools such as static site generators or documentation tools. In order to use marimo islands, you need to import the necessary JS/CSS headers in your HTML file, and use our custom HTML tags to define the islands. `[](#__codelineno-18-1) [](#__codelineno-18-2) [](#__codelineno-18-10) [](#__codelineno-18-11) [](#__codelineno-18-12) [](#__codelineno-18-16) [](#__codelineno-18-22) [](#__codelineno-18-23)[](#__codelineno-18-24) [](#__codelineno-18-25) [](#__codelineno-18-26) [](#__codelineno-18-27) [](#__codelineno-18-28) Hello, islands! [](#__codelineno-18-29) [](#__codelineno-18-30) [](#__codelineno-18-31) [](#__codelineno-18-32) [](#__codelineno-18-33)` marimo.MarimoIslandGenerator [¶](#marimo.MarimoIslandGenerator "Permanent link") -------------------------------------------------------------------------------- `[](#__codelineno-0-1)MarimoIslandGenerator(app_id: [str](https://docs.python.org/3/library/stdtypes.html#str) = 'main')` Generates Marimo islands for embedding in other pages. This is a great way to use another SSG framework that converts Python code to HTML using marimo-islands. Generally you will want to: 1. Find all the code snippets and add them to the generator. 2. Build the app. 3. Replace all code snippets with the rendered HTML. 4. Include the header in the tag. Examples: Using the MarimoIslandGenerator class: `[](#__codelineno-0-1)import asyncio [](#__codelineno-0-2)import sys [](#__codelineno-0-3)from marimo import MarimoIslandGenerator [](#__codelineno-0-4)[](#__codelineno-0-5)async def main(): [](#__codelineno-0-6) generator = MarimoIslandGenerator() [](#__codelineno-0-7) block1 = generator.add_code("import marimo as mo") [](#__codelineno-0-8) block2 = generator.add_code("mo.md('Hello, islands!')") [](#__codelineno-0-9) [](#__codelineno-0-10) # Build the app [](#__codelineno-0-11) app = await generator.build() [](#__codelineno-0-12) [](#__codelineno-0-13) # Render the app [](#__codelineno-0-14) output = f""" [](#__codelineno-0-15) [](#__codelineno-0-16) [](#__codelineno-0-17) {generator.render_head()} [](#__codelineno-0-18) [](#__codelineno-0-19) [](#__codelineno-0-20) {block1.render(display_output=False)} [](#__codelineno-0-21) {block2.render()} [](#__codelineno-0-22) [](#__codelineno-0-23) [](#__codelineno-0-24) """ [](#__codelineno-0-25) print(output) [](#__codelineno-0-26) # Save the HTML to a file [](#__codelineno-0-27) output_file = "output.html" [](#__codelineno-0-28) with open(output_file, "w", encoding="utf-8") as f: [](#__codelineno-0-29) f.write(output) [](#__codelineno-0-30)[](#__codelineno-0-31)if __name__ == '__main__': [](#__codelineno-0-32) asyncio.run(main())` You can also create the generator from a file: `[](#__codelineno-1-1)from marimo import MarimoIslandGenerator [](#__codelineno-1-2)[](#__codelineno-1-3)# Create the generator from file [](#__codelineno-1-4)generator = MarimoIslandGenerator.from_file( [](#__codelineno-1-5) "./.py", display_code=False [](#__codelineno-1-6)) [](#__codelineno-1-7)[](#__codelineno-1-8)# Generate and print the HTML without building [](#__codelineno-1-9)# This will still work for basic rendering, though without running the cells [](#__codelineno-1-10)html = generator.render_html(include_init_island=False) [](#__codelineno-1-11)print(html) [](#__codelineno-1-12)# Save the HTML to a file [](#__codelineno-1-13)output_file = "output.html" [](#__codelineno-1-14)with open(output_file, "w", encoding="utf-8") as f: [](#__codelineno-1-15) f.write(html)` | PARAMETER | DESCRIPTION | | --- | --- | | `app_id` | The optional identifier of the app, defaults to `main`. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `'main'` | ### has\_run `instance-attribute` [¶](#marimo.MarimoIslandGenerator.has_run "Permanent link") ### add\_code [¶](#marimo.MarimoIslandGenerator.add_code "Permanent link") `[](#__codelineno-0-1)add_code( [](#__codelineno-0-2) code: [str](https://docs.python.org/3/library/stdtypes.html#str), [](#__codelineno-0-3) display_code: [bool](https://docs.python.org/3/library/functions.html#bool) = False, [](#__codelineno-0-4) display_output: [bool](https://docs.python.org/3/library/functions.html#bool) = True, [](#__codelineno-0-5) is_reactive: [bool](https://docs.python.org/3/library/functions.html#bool) = True, [](#__codelineno-0-6) is_raw: [bool](https://docs.python.org/3/library/functions.html#bool) = False, [](#__codelineno-0-7)) -> MarimoIslandStub` Add a code cell to the app. _Args:_ * code (str): The code to add to the app. * display\_code (bool): Whether to display the code in the HTML. * display\_output (bool): Whether to display the output in the HTML. * is\_raw (bool): Whether to handled the code without formatting. * is\_reactive (bool): Whether this code block will run with pyodide. ### build `async` [¶](#marimo.MarimoIslandGenerator.build "Permanent link") Build the app. This should be called after adding all the code cells. _Returns:_ * App: The built app. ### from\_file `staticmethod` [¶](#marimo.MarimoIslandGenerator.from_file "Permanent link") `[](#__codelineno-0-1)from_file( [](#__codelineno-0-2) filename: [str](https://docs.python.org/3/library/stdtypes.html#str), display_code: [bool](https://docs.python.org/3/library/functions.html#bool) = False [](#__codelineno-0-3)) -> [MarimoIslandGenerator](#marimo.MarimoIslandGenerator " marimo.MarimoIslandGenerator (marimo._islands._island_generator.MarimoIslandGenerator)")` Create a MarimoIslandGenerator and populate MarimoIslandStubs using code cells from a marimo \*.py file. _Args:_ * filename (str): Marimo .py filename to convert to reactive HTML. * display\_code (bool): Whether to display the code in HTML snippets. ### render\_body [¶](#marimo.MarimoIslandGenerator.render_body "Permanent link") Render the body for the app. This should be included in the tag of the page. _Args:_ - include\_init\_island (bool): If True, adds initialization loader. - max\_width (str): CSS style max\_width property. - margin (str): CSS style margin property. - style (str): CSS style. Overrides max\_width and margin. ### render\_head [¶](#marimo.MarimoIslandGenerator.render_head "Permanent link") `[](#__codelineno-0-1)render_head( [](#__codelineno-0-2) *, [](#__codelineno-0-3) version_override: [str](https://docs.python.org/3/library/stdtypes.html#str) = __version__, [](#__codelineno-0-4) _development_url: [Union](https://docs.python.org/3/library/typing.html#typing.Union "typing.Union")[[str](https://docs.python.org/3/library/stdtypes.html#str), [bool](https://docs.python.org/3/library/functions.html#bool)] = False [](#__codelineno-0-5)) -> [str](https://docs.python.org/3/library/stdtypes.html#str)` Render the header for the app. This should be included in the tag of the page. _Args:_ * version\_override (str): Marimo version to use for loaded js/css. * \_development\_url (str): If True, uses local marimo islands js. ### render\_html [¶](#marimo.MarimoIslandGenerator.render_html "Permanent link") Render reactive html for the app. _Args:_ * version\_override (str): Marimo version to use for loaded js/css. * \_development\_url (str): If True, uses local marimo islands js. * include\_init\_island (bool): If True, adds initialization loader. * max\_width (str): CSS style max\_width property. * margin (str): CSS style margin property. * style (str): CSS style. Overrides max\_width and margin. ### render\_init\_island [¶](#marimo.MarimoIslandGenerator.render_init_island "Permanent link") `[](#__codelineno-0-1)render_init_island() -> [str](https://docs.python.org/3/library/stdtypes.html#str)` Renders a static html MarimoIsland str which displays a spinning initialization loader while Pyodide loads and disappears once the kernel is ready to use. Publish to the web - marimo https://docs.marimo.io/guides/publishing/ Publishing notebooks to the web[¶](#publishing-notebooks-to-the-web "Permanent link") ------------------------------------------------------------------------------------- You can publish marimo notebooks to the web as interactive editable notebooks, readonly web apps, or [static documents](https://docs.marimo.io/guides/exporting/). Thanks to [WebAssembly](https://docs.marimo.io/guides/wasm/), you can even share executable notebooks on GitHub Pages or other static sites without paying for backend infrastrcture. This makes it easy to share your work with colleagues, embed executable notebooks in web documentation or educational websites, and more. This guide provides an overview of the various ways to publish marimo notebooks. | Guide | Description | | --- | --- | | [Embedding](https://docs.marimo.io/guides/publishing/embedding/) | An overview of embedding notebooks in other sites | | [From GitHub](https://docs.marimo.io/guides/publishing/from_github/) | Share links to executable notebooks hosted on GitHub | | [From code snippets](https://docs.marimo.io/guides/publishing/from_code_snippets/) | Convert code snippets in Markdown or HTML to interactive notebooks | | [GitHub Pages](https://docs.marimo.io/guides/publishing/github_pages/) | Publish interactive notebooks on GitHub Pages | | [Cloudflare](https://docs.marimo.io/guides/publishing/cloudflare/) | Publish interactive notebooks on Cloudflare | | [Online playground](https://docs.marimo.io/guides/publishing/playground/) | Share links to notebooks using our online playground | | [Community Cloud](https://docs.marimo.io/guides/publishing/community_cloud/) | Save notebooks to our free Community Cloud | | [Self-host WebAssembly notebooks](https://docs.marimo.io/guides/publishing/self_host_wasm/) | Self-hosting interactive WebAssembly (HTML export) notebooks | | [View notebooks on GitHub](https://docs.marimo.io/guides/publishing/view_outputs_on_github/) | Viewing notebook outputs on GitHub | | [Deploy on a backend](https://docs.marimo.io/guides/publishing/deploy/) | Deploying notebooks on backends | | [With MkDocs](https://docs.marimo.io/guides/publishing/mkdocs/) | Publish reactive websites with MkDocs from markdown | | [With Quarto](https://docs.marimo.io/guides/publishing/quarto/) | Publish reactive websites with Quarto from markdown | Share cloud notebooks with molab - marimo https://docs.marimo.io/guides/molab/ [molab](https://molab.marimo.io/notebooks) is a cloud-hosted marimo notebook workspace that lets you rapidly experiment on data using Python and SQL. We’re giving molab (**mo** for marimo) to you, our community, for _free_. To create your first notebook, visit: [https://molab.marimo.io/notebooks](https://molab.marimo.io/notebooks). Contribute example notebooks! We welcome exciting companies and projects to contribute examples notebooks, which are featured on the homepage with an organization's name and logo. To propose an example, [reach out to us on GitHub](https://github.com/marimo-team/marimo/issues). **Highlights**. * ⚡️ Build powerful notebooks using [marimo](https://github.com/marimo-team/marimo), a next-gen open-source Python notebook built entirely from scratch that [solves](https://marimo.io/blog/lessons-learned) [long-standing](https://marimo.io/blog/python-not-json) [problems](https://leomurta.github.io/papers/pimentel2019a.pdf) with Jupyter * ☁️ Use any Python package, thanks to our cloud backend * 🤖 Generate code with AI * 📦 Upload data files * 🔗 Share links and badges (notebooks are public but undiscoverable, like secret GitHub Gists) * 📥 Download notebooks to your machine, reuse them as Python scripts or apps * 📤 Upload local notebooks to the cloud from our CLI (coming soon) * 🕹️ Real-time collaboration (coming soon) * 🧩 Configure computational resources to obtain more CPU or GPU (coming soon) Sharing[¶](#sharing "Permanent link") ------------------------------------- molab notebooks are public but undiscoverable by default. ### URL[¶](#url "Permanent link") You can share notebooks by URL. Here's an example: > [https://molab.marimo.io/notebooks/nb\_TWVGCgZZK4L8zj5ziUBNVL](https://molab.marimo.io/notebooks/nb_TWVGCgZZK4L8zj5ziUBNVL) ### Open in molab badge[¶](#open-in-molab-badge "Permanent link") Share links to molab notebooks using our open in molab badge: Use the following markdown snippet (replace the notebook URL with a link to your own notebook): `[](#__codelineno-0-1)[![Open in molab](https://marimo.io/molab-shield.png)](https://marimo.io/notebooks/nb_UJPnqcQzB7NuTtVNhwYBBp)` Packages[¶](#packages "Permanent link") --------------------------------------- Each notebook runs in an environment with several popular packages pre-installed, including torch, numpy, polars, and more. marimo’s built-in package manager will install additional packages as you import them (use the package manage panel to install specific package versions). Storage[¶](#storage "Permanent link") ------------------------------------- Notebooks get persistent storage; view the file tree by clicking the file icon in the sidebar. From here you can upload additional data files, which are stored in a Cloudflare R2 bucket. Run notebook locally[¶](#run-notebook-locally "Permanent link") --------------------------------------------------------------- You can download the notebook directory by clicking the download button, also on the top-right. You can also just pass the notebook URL to marimo edit. For example: `[](#__codelineno-1-1)marimo edit https://molab.marimo.io/notebooks/nb_TWVGCgZZK4L8zj5ziUBNVL` Today, this brings just the notebook file down, and does not include your attached storage. FAQ[¶](#faq "Permanent link") ----------------------------- **What’s the difference between molab and Google Colab?** Google Colab is a hosted Jupyter notebook service provider. molab is a hosted [marimo notebook](https://github.com/marimo-team/marimo) service with similar compute and sharing capabilities, but powered by marimo notebooks instead of Jupyter. **Is molab marimo’s enterprise product?** No. If you’re interested in a next-generation data platform for modern AI and data workloads — with marimo’s trademark developer experience, complete with security and governance required for enterprises — [get in touch](mailto:contact@marimo.io). **Is molab free?** molab is currently free to use, as long as usage is reasonable. Our goal is to make is as easy as possible for our community to use marimo notebooks. **How do I get more RAM, CPU or GPUs?** [Reach out to us](https://marimo.io/discord) and we’ll see what we can do! **I’m a compute provider. How do I get plugged into molab as an offered backend?** [Get in touch](mailto:contact@marimo.io). **How does molab relate to marimo’s open source notebook?** molab is a hosted version of marimo’s open source notebook. You can use marimo on your own machine or on your own remote servers. **How does molab relate to marimo’s WebAssembly playground?** The [WebAssembly playground](https://marimo.app/) runs notebooks entirely in the browser through [Pyodide](https://pyodide.org/en/stable/). This makes for a snappy user experience, at the cost of limited compute and limited support for Python packages. The playground is well-suited for lightweight notebooks and embedding interactive notebooks in documentation, but it is not well-suited for modern ML or AI workflows. molab is currently entirely separate from the WebAssembly playground. In the future we may merge them into a unified experience. **How does molab relate to marimo’s community cloud?** Our [community cloud](https://marimo.io/dashboard) provides a place to organize and share WebAssembly notebooks. molab is currently entirely separate from the community cloud. In the future we may merge them into a unified experience. **Why are you making molab?** See our [announcement blog post](https://marimo.io/blog/announcing-molab). Embedding - marimo https://docs.marimo.io/guides/publishing/embedding/ There are various ways to embed marimo notebooks in other web pages, such as web documentation, educational platforms, or static sites in general. Here are the main approaches: * Host on [GitHub Pages](https://docs.marimo.io/guides/publishing/github_pages/) or [self-host WASM HTML](https://docs.marimo.io/guides/publishing/self_host_wasm/), and `` * **`allow-scripts`**: Required for JavaScript execution (essential for marimo to run) Basic Functionality With only `allow-scripts`, marimo will work but with limitations: WebSocket connections will function, but storage will be in-memory only (state resets on page reload), and clipboard access will use browser prompts instead of the clipboard API. ### Recommended Sandbox Attributes[¶](#recommended-sandbox-attributes "Permanent link") For the best user experience, include these additional attributes: `[](#__codelineno-1-1)` **Additional Attributes:** * **`allow-same-origin`**: Enables persistent storage (localStorage) and full clipboard API. Only use this if you trust the content of the iframe or the iframe URL is hosted on a different domain. * **`allow-downloads`**: Enables downloading notebook outputs, data exports, and screenshots * **`allow-popups`**: Allows opening links and notebooks in new tabs * **`allowfullscreen`** (attribute, not sandbox): Enables fullscreen mode for slides and outputs **Permission Policy:** * **`allow="microphone"`**: Required for `mo.ui.microphone()` widget functionality Security Considerations Only use `allow-same-origin` with trusted content or the iframe URL is hosted on a different domain. Combining `allow-scripts` and `allow-same-origin` allows the iframe to remove the sandbox attribute entirely, making the iframe as powerful as if it weren't sandboxed at all. ### Example: Full Configuration[¶](#example-full-configuration "Permanent link") Here's a complete example with all recommended settings: `[](#__codelineno-2-1)` From GitHub - marimo https://docs.marimo.io/guides/publishing/from_github/ marimo makes it very easy to share links to executable notebooks from notebooks hosted on GitHub. Unlike Google Colab, marimo also automatically synchronizes data stored in your GitHub repo to the notebook's filesystem, making it easy to bundle data with your notebooks. * Publish notebooks to [GitHub Pages](https://docs.marimo.io/guides/publishing/github_pages/) * Edit notebooks on the [marimo playground](https://docs.marimo.io/guides/publishing/playground/), with public link-based sharing (no login required!) * Synchronize to our [Community Cloud](https://docs.marimo.io/guides/publishing/community_cloud/) for email-based sharing From code snippets - marimo https://docs.marimo.io/guides/publishing/from_code_snippets/ Publish using `marimo-snippets`[¶](#publish-using-marimo-snippets "Permanent link") ----------------------------------------------------------------------------------- [`marimo-snippets`](https://github.com/marimo-team/marimo-snippets) is a single-file JavaScript utility that lets you embed interactive marimo notebooks in static web pages, powered by WebAssembly. Simply wrap code elements in a custom tag, and `marimo-snippets` does the rest; `marimo-snippets` is even compatible with MkDocs-processed markdown! Here's a demo: `[](#__codelineno-0-1)
[](#__codelineno-0-2) [](#__codelineno-0-3)```python [](#__codelineno-0-4)import marimo as mo [](#__codelineno-0-5)``` [](#__codelineno-0-6)```python [](#__codelineno-0-7)slider = mo.ui.slider(1, 10) [](#__codelineno-0-8)slider [](#__codelineno-0-9)``` [](#__codelineno-0-10)[](#__codelineno-0-11)```python [](#__codelineno-0-12)slider.value * "🍃" [](#__codelineno-0-13)``` [](#__codelineno-0-14) [](#__codelineno-0-15)
[](#__codelineno-0-16)[](#__codelineno-0-17)` This embeds an iframe on your page with an interactive slider, like the one below. Fun fact: this page is itself using `marimo-snippets`! `[](#__codelineno-2-1)slider = mo.ui.slider(1, 10) [](#__codelineno-2-2)slider` Configuration[¶](#configuration "Permanent link") ------------------------------------------------- To configure the rendering behavior globally, you can include script elements _before_ the marimo snippets script. `[](#__codelineno-4-1) [](#__codelineno-4-2) [](#__codelineno-4-3) [](#__codelineno-4-7)[](#__codelineno-4-8)` You can also configure data attributes per-element. `[](#__codelineno-5-1) [](#__codelineno-5-2)... [](#__codelineno-5-3)` See the [GitHub repository](https://github.com/marimo-team/marimo-snippets) for a full example and [documentation on configuration](https://github.com/marimo-team/marimo-snippets?tab=readme-ov-file#configuration). GitHub Pages - marimo https://docs.marimo.io/guides/publishing/github_pages/ Publish to GitHub Pages[¶](#publish-to-github-pages "Permanent link") --------------------------------------------------------------------- You can publish executable notebooks to [GitHub Pages](https://pages.github.com/) for free, after exporting your notebook to a WebAssembly notebook. Export to WASM-powered HTML[¶](#export-to-wasm-powered-html "Permanent link") ----------------------------------------------------------------------------- Export your notebook to a self-contained HTML file that runs using [WebAssembly](https://docs.marimo.io/guides/wasm/): Export as a readonly appExport as an editable notebook `[](#__codelineno-0-1)marimo export html-wasm notebook.py -o output_dir --mode run` `[](#__codelineno-1-1)marimo export html-wasm notebook.py -o output_dir --mode edit` See our [exporting guide](https://docs.marimo.io/guides/exporting/#export-to-wasm-powered-html) for the full documentation. Publish using GitHub Actions[¶](#publish-using-github-actions "Permanent link") ------------------------------------------------------------------------------- Template repository Fork our [template repository](https://github.com/marimo-team/marimo-gh-pages-template) for deploying multiple notebooks to GitHub Pages. Once you have forked the repository, add your notebooks to the `notebooks` or `apps` directories, for editable or readonly respectively. Publish to GitHub Pages using the following GitHub Actions workflow, which will republish your notebook on git push. `[](#__codelineno-2-1)jobs: [](#__codelineno-2-2) build: [](#__codelineno-2-3) runs-on: ubuntu-latest [](#__codelineno-2-4) [](#__codelineno-2-5) steps: [](#__codelineno-2-6) # ... checkout and install dependencies [](#__codelineno-2-7) [](#__codelineno-2-8) - name: 📄 Export notebook [](#__codelineno-2-9) run: | [](#__codelineno-2-10) marimo export html-wasm notebook.py -o path/to/output --mode run [](#__codelineno-2-11) [](#__codelineno-2-12) - name: 📦 Upload Pages Artifact [](#__codelineno-2-13) uses: actions/upload-pages-artifact@v3 [](#__codelineno-2-14) with: [](#__codelineno-2-15) path: path/to/output [](#__codelineno-2-16) [](#__codelineno-2-17) deploy: [](#__codelineno-2-18) needs: build [](#__codelineno-2-19) runs-on: ubuntu-latest [](#__codelineno-2-20) environment: [](#__codelineno-2-21) name: github-pages [](#__codelineno-2-22) url: ${{ steps.deployment.outputs.page_url }} [](#__codelineno-2-23) [](#__codelineno-2-24) permissions: [](#__codelineno-2-25) pages: write [](#__codelineno-2-26) id-token: write [](#__codelineno-2-27) [](#__codelineno-2-28) steps: [](#__codelineno-2-29) - name: 🌐 Deploy to GitHub Pages [](#__codelineno-2-30) id: deployment [](#__codelineno-2-31) uses: actions/deploy-pages@v4 [](#__codelineno-2-32) with: [](#__codelineno-2-33) artifact_name: github-pages` Publish manually[¶](#publish-manually "Permanent link") ------------------------------------------------------- You can also publish an exported notebook manually through your repository settings. Read [GitHub's documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) to learn more. Make sure to [include a `.nojekyll` file](https://github.blog/news-insights/bypassing-jekyll-on-github-pages/) in root folder from which your site is built to prevent GitHub from interfering with your site. Cloudflare - marimo https://docs.marimo.io/guides/publishing/cloudflare/ Publish to Cloudflare[¶](#publish-to-cloudflare "Permanent link") ----------------------------------------------------------------- You can publish executable notebooks to [Cloudflare Workers](https://workers.cloudflare.com/) for free, after exporting your notebook to a WebAssembly notebook. Export to WASM-powered HTML[¶](#export-to-wasm-powered-html "Permanent link") ----------------------------------------------------------------------------- Export your notebook to a self-contained HTML file that runs using [WebAssembly](https://docs.marimo.io/guides/wasm/) with the flag `--include-cloudflare`: Export as a readonly appExport as an editable notebook `[](#__codelineno-0-1)marimo export html-wasm notebook.py -o output_dir --mode run --include-cloudflare` `[](#__codelineno-1-1)marimo export html-wasm notebook.py -o output_dir --mode edit --include-cloudflare` See our [exporting guide](https://docs.marimo.io/guides/exporting/#export-to-wasm-powered-html) for the full documentation. Publish to a Cloudflare Worker[¶](#publish-to-a-cloudflare-worker "Permanent link") ----------------------------------------------------------------------------------- When you use the `--include-cloudflare` flag, marimo creates two additional files in the parent directory of your output directory: * `index.js`: A simple Cloudflare Worker script that serves your static assets * `wrangler.jsonc`: Configuration for Cloudflare's Wrangler CLI To run locally, run: To deploy to Cloudflare, run: Need authentication or custom endpoints? You can modify the `index.js` to include authentication or custom endpoints. This allows you to: * Add authentication logic to protect your notebook * Create API endpoints that serve data from the same domain, avoiding CORS issues Publish to Cloudflare Pages using GitHub[¶](#publish-to-cloudflare-pages-using-github "Permanent link") ------------------------------------------------------------------------------------------------------- As an alternative to Cloudflare Workers, you can publish to Cloudflare Pages. To get started, create a new GitHub repository by visiting [repo.new](https://repo.new/) . After creating a new repository, go to your newly created project directory to prepare and push your local application to GitHub by running the following commands in your terminal: `[](#__codelineno-4-1)cd output_dir [](#__codelineno-4-2)git init [](#__codelineno-4-3)git remote add origin https://github.com// [](#__codelineno-4-4)git add . [](#__codelineno-4-5)git commit -m "Initial commit" [](#__codelineno-4-6)git branch -M main [](#__codelineno-4-7)git push -u origin main` To deploy your site to Pages: 1. Log in to the Cloudflare [Dashboard](https://dash.cloudflare.com/) and select your account. 2. In Account Home, select Workers & Pages > Create application > Pages > Connect to Git. 3. Select the new GitHub repository that you created and, in the Set up builds and deployments section, provide the following information: `[](#__codelineno-5-1)Project name output-dir [](#__codelineno-5-2)Production branch main [](#__codelineno-5-3)Framework preset None [](#__codelineno-5-4)Build command (optional) exit 0 [](#__codelineno-5-5)Build output directory /` 4. Save and Deploy Publish to Cloudflare Pages Manually[¶](#publish-to-cloudflare-pages-manually "Permanent link") ----------------------------------------------------------------------------------------------- To deploy your site to Pages: 1. Create zip of the folder "output\_dir" 2. Log in to the Cloudflare [Dashboard](https://dash.cloudflare.com/) and select your account. 3. In Account Home, select Workers & Pages > Create application > Pages > Upload asset. 4. Enter a project name then click Upload and select output\_dir.zip . 5. Save and Deploy Community Cloud - marimo https://docs.marimo.io/guides/publishing/community_cloud/ Our [Community Cloud](https://marimo.io/dashboard) is a free workspace for creating, saving, and sharing marimo notebooks. Unlike the [Playground](https://docs.marimo.io/guides/publishing/playground/), the Community Cloud requires a login. In return, it lets you save noteoboks, share them using email-based authorization, and upload a limited amount of data. WebAssembly notebooks only Currently, the Community Cloud only allows the creation of [WebAssembly notebooks](https://docs.marimo.io/guides/wasm/). These are easy to share and embed in other web pages, but have some limitations in packages and performance. Note: unlike our other publishing options, it is not possible to embed editable Community Cloud notebooks in other web pages. Self-host WASM - marimo https://docs.marimo.io/guides/publishing/self_host_wasm/ Self-host WebAssembly notebooks[¶](#self-host-webassembly-notebooks "Permanent link") ------------------------------------------------------------------------------------- As an alternative to [GitHub Pages](https://docs.marimo.io/guides/publishing/github_pages/), it is possible to self-host exported [WebAssembly notebooks](https://docs.marimo.io/guides/wasm/): * [Export to WASM HTML](https://docs.marimo.io/guides/exporting/#export-to-wasm-powered-html). * Serve the exported file over HTTP. * Serve the assets in the `assets` directory, next to the HTML file. * Possibly configure your web server to support serving `application/wasm/` files with the correct headers. View outputs on GitHub - marimo https://docs.marimo.io/guides/publishing/view_outputs_on_github/ marimo notebooks are stored as pure Python files, in order to work with Git versioning and the broader Python ecosystem. However, this means that unlike Jupyter notebooks, by default you cannot see marimo notebook outputs on GitHub. If you would like to make outputs viewable on GitHub, you can configure any given marimo notebook to automatically snapshot its outputs to an `ipynb` file. The snapshot will be saved to a `__marimo__` directory in the same folder where the notebook lives, which you can then push to GitHub. Enable snapshotting in the notebook settings menu, using the gear icon in the top right of any notebook. Deploy a backend - marimo https://docs.marimo.io/guides/publishing/deploy/ Deploy on backends[¶](#deploy-on-backends "Permanent link") ----------------------------------------------------------- If you cannot use WebAssembly notebooks, you can deploy marimo notebooks via a traditional client-server model. Both the edit server can be deployed as well as individual notebooks (as readonly apps). Learn more in our [Deployment Guide](https://docs.marimo.io/guides/deploying/). Deploy notebooks - marimo https://docs.marimo.io/guides/deploying/ Deploying[¶](#deploying "Permanent link") ----------------------------------------- You can deploy marimo in three ways: 1. via an **edit server**, which allows you to create and edit notebooks. On the CLI, this is launched with `marimo edit`, and is similar to `jupyter notebook`. 2. via a **run server**, which allows you serve marimo notebooks as read-only web apps. On the CLI, this is launched with `marimo run notebook.py` 3. programmatically, which allows you serve **read-only** marimo apps as part of other ASGI applications, for example using FastAPI. Sharing lightweight notebooks on the web To share notebooks on the public web, try using [our online playground](https://marimo.new/). Our playground runs entirely in the browser -- no backend required, via [WASM](https://docs.marimo.io/guides/wasm/). Or, to share notebooks with email-based authorization, you can also try our free [community cloud](https://marimo.io/sign-up), which is also powered by WASM. WASM notebooks support most but not all Python features and packages. Deploying an edit server[¶](#deploying-an-edit-server "Permanent link") ----------------------------------------------------------------------- Here are a few ways to deploy an edit server on a remote instance: 1. With [ssh-port forwarding](https://docs.marimo.io/faq/#faq-remote), using `marimo edit --headless`. 2. Via docker and our [prebuilt containers](https://docs.marimo.io/guides/deploying/prebuilt_containers/). 3. Via a deployment service [such as Railway](https://docs.marimo.io/guides/deploying/deploying_railway/). 4. [Behind JupyterHub](https://docs.marimo.io/faq/#faq-jupyter-hub). Deploying as read-only apps[¶](#deploying-as-read-only-apps "Permanent link") ----------------------------------------------------------------------------- These guides help you deploy marimo notebooks as read-only apps. | | | | --- | --- | | [programmatically](https://docs.marimo.io/guides/deploying/programmatically/) | Programmatically run and customize read-only marimo apps | | [deploying\_docker](https://docs.marimo.io/guides/deploying/deploying_docker/) | Deploy with Docker | | [authentication](https://docs.marimo.io/guides/deploying/authentication/) | Authentication and security | | [deploying\_public\_gallery](https://docs.marimo.io/guides/deploying/deploying_public_gallery/) | Deploy to our public gallery | | [deploying\_hugging\_face](https://docs.marimo.io/guides/deploying/deploying_hugging_face/) | Deploy to Hugging Face | | [deploying\_ploomber](https://docs.marimo.io/guides/deploying/deploying_ploomber/) | Deploy to Ploomber Cloud | ### Health and status endpoints[¶](#health-and-status-endpoints "Permanent link") The following endpoints may be useful when deploying your application: * `/health` - A health check endpoint that returns a 200 status code if the application is running as expected * `/healthz` - Same as above, just a different name for easier integration with cloud providers * `/api/status` - A status endpoint that returns a JSON object with the status of the server ### Configuration[¶](#configuration "Permanent link") If you would like to deploy your application at a subpath, you can set the `--base-url` flag when running your application. `[](#__codelineno-0-1)marimo run app.py --base-url /subpath` ### Including code in your application[¶](#including-code-in-your-application "Permanent link") You can include code in your application by using the `--include-code` flag when running your application. `[](#__codelineno-1-1)marimo run app.py --include-code` Authentication - marimo https://docs.marimo.io/guides/deploying/authentication/ marimo provides a simple way to add token/password protection to your marimo server. Given that authentication is a complex topic, marimo does not provide a built-in authentication/authorization system, but instead makes it easy to add your own through ASGI middleware. Enabling Basic Authentication[¶](#enabling-basic-authentication "Permanent link") --------------------------------------------------------------------------------- Authentication is enabled by default when running `marimo edit/tutorial/new`. To disable authentication, you may pass `--no-token` to your `marimo edit/run/new` command from the Terminal. The auth token will be randomly generated when in `Edit mode` and deterministically generated in `Run mode` (based on the code of the notebook). However, you can also pass your own token/password using the `--token-password` flag. `[](#__codelineno-0-1)marimo run my_notebook.py --token --token-password="sup3rs3cr3t"` ### Ways to Authenticate[¶](#ways-to-authenticate "Permanent link") In order to authenticate, you must either pass the token as a password in the `Authorization` header, or as a query parameter under `access_token` in the URL. 1. Enter the token in the login page: If you try to access marimo from a browser, you will be redirected to a login page where you can enter the token. 2. Query parameter: To authenticate using a query parameter, you must pass the token as a query parameter under `access_token` in the URL. For example, to authenticate with the token `sup3rs3cr3t`, you would pass the query parameter `http://localhost:2718?access_token=sup3rs3cr3t`. For convenience, when running locally, marimo will automatically open the URL with the query parameter in your default browser. 3. Basic Authorization header: To authenticate using the `Authorization` header, you must pass the token as a password in the `Authorization` header using the [Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). For example, to authenticate with the token `sup3rs3cr3t`, you would pass the header `Authorization Basic base64("any_username:sup3rs3cr3t")`. This is not necessary when using a browser, as the marimo server will redirect you to a minimal login page where you can enter the token. Custom Authentication[¶](#custom-authentication "Permanent link") ----------------------------------------------------------------- If you choose to make your marimo application public, you may want to add your own authentication system, along with authorization, rate limiting, etc. You can do this by creating a marimo application programmatically and adding your own middleware to the ASGI application. Here's an example of how you can add authentication to a marimo application using FastAPI: `[](#__codelineno-1-1)from typing import Annotated, Callable, Coroutine [](#__codelineno-1-2)from fastapi.responses import HTMLResponse, RedirectResponse [](#__codelineno-1-3)import marimo [](#__codelineno-1-4)from fastapi import FastAPI, Form, Request, Response [](#__codelineno-1-5)# Custom auth middleware and login page [](#__codelineno-1-6)from my_auth_module import auth_middleware, my_login_route [](#__codelineno-1-7) [](#__codelineno-1-8)[](#__codelineno-1-9)# Create a marimo asgi app [](#__codelineno-1-10)server = ( [](#__codelineno-1-11) marimo.create_asgi_app() [](#__codelineno-1-12) .with_app(path="", root="./pages/index.py") [](#__codelineno-1-13) .with_app(path="/dashboard", root="./pages/dashboard.py") [](#__codelineno-1-14) .with_app(path="/sales", root="./pages/sales.py") [](#__codelineno-1-15)) [](#__codelineno-1-16)[](#__codelineno-1-17)# Create a FastAPI app [](#__codelineno-1-18)app = FastAPI() [](#__codelineno-1-19)[](#__codelineno-1-20)app.add_middleware(auth_middleware) [](#__codelineno-1-21)app.add_route("/login", my_login_route, methods=["POST"]) [](#__codelineno-1-22)[](#__codelineno-1-23)app.mount("/", server.build()) [](#__codelineno-1-24)[](#__codelineno-1-25)# Run the server [](#__codelineno-1-26)if __name__ == "__main__": [](#__codelineno-1-27) import uvicorn [](#__codelineno-1-28) [](#__codelineno-1-29) uvicorn.run(app, host="localhost", port=8000)` For for a full example on implementing OAuth2 with FastAPI, see the [FastAPI OAuth2 example](https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/). Docker - marimo https://docs.marimo.io/guides/deploying/deploying_docker/ Deploy with Docker[¶](#deploy-with-docker "Permanent link") ----------------------------------------------------------- Prerequisites[¶](#prerequisites "Permanent link") ------------------------------------------------- * A marimo notebook or app: `app.py` that you want to deploy * A `requirements.txt` file that contains the dependencies needed for your application to run Create a Dockerfile[¶](#create-a-dockerfile "Permanent link") ------------------------------------------------------------- `Dockerfile` is a text file that contains instructions for building a Docker image. Here's an example `Dockerfile` for a marimo notebook: `[](#__codelineno-0-1)# syntax=docker/dockerfile:1.4 [](#__codelineno-0-2)[](#__codelineno-0-3)# Choose a python version that you know works with your application [](#__codelineno-0-4)FROM python:3.11-slim [](#__codelineno-0-5)[](#__codelineno-0-6)# Install uv for fast package management [](#__codelineno-0-7)COPY --from=ghcr.io/astral-sh/uv:0.4.20 /uv /bin/uv [](#__codelineno-0-8)ENV UV_SYSTEM_PYTHON=1 [](#__codelineno-0-9)[](#__codelineno-0-10)WORKDIR /app [](#__codelineno-0-11)[](#__codelineno-0-12)# Copy requirements file [](#__codelineno-0-13)COPY --link requirements.txt . [](#__codelineno-0-14)[](#__codelineno-0-15)# Install the requirements using uv [](#__codelineno-0-16)RUN uv pip install -r requirements.txt [](#__codelineno-0-17)[](#__codelineno-0-18)# Copy application files [](#__codelineno-0-19)COPY --link app.py . [](#__codelineno-0-20)# Uncomment the following line if you need to copy additional files [](#__codelineno-0-21)# COPY --link . . [](#__codelineno-0-22)[](#__codelineno-0-23)EXPOSE 8080 [](#__codelineno-0-24)[](#__codelineno-0-25)# Create a non-root user and switch to it [](#__codelineno-0-26)RUN useradd -m app_user [](#__codelineno-0-27)USER app_user [](#__codelineno-0-28)[](#__codelineno-0-29)CMD [ "marimo", "run", "app.py", "--host", "0.0.0.0", "-p", "8080" ]` Breaking it down[¶](#breaking-it-down "Permanent link") ------------------------------------------------------- `FROM` instructs what base image to choose. In our case, we chose Python 3.11 with the “slim” variant. This removes a lot of extra dependencies. You can always add them back as needed. A slimmer Dockerfile (by bytes) means quick to build, deploy, and start up. The `WORKDIR` sets the current working directory. In most cases, this does not need to be changed. The `COPY` steps will copy all the necessary files into your docker. By adding `--link`, we end up creating a new layer that does not get invalidated by previous changes. This can be especially important for expensive install steps that do not depend on each other. `RUN` lets us run shell commands. We can use this to install dependencies via apt-get, pip, or package managers. In our case, we use it to install our requirements.txt with pip. Our `EXPOSE` step tells us which port is exposed to be accessed from outside the Docker container. This will need to match the port at which we run our marimo application on. We then create a new user and switch to it with the `USER` instruction, in order to limit the permissions of the marimo application. This is not required, but recommended. The final step `CMD` instructions what command to run when we run our docker container. Here we run our marimo application at the port 8080. Running your application locally[¶](#running-your-application-locally "Permanent link") --------------------------------------------------------------------------------------- Once you have your Dockerfile and your application files, you can test it out locally: `[](#__codelineno-1-1)# Build your image, and tag it as my_app [](#__codelineno-1-2)docker build -t my_app . [](#__codelineno-1-3)[](#__codelineno-1-4)# Start your container, mapping port 8080 [](#__codelineno-1-5)docker run -p 8080:8080 -it my_app [](#__codelineno-1-6)[](#__codelineno-1-7)# Visit http://localhost:8080` After verifying that your application runs without errors, you can use these files to deploy your application on your preferred cloud provider that supports dockerized applications. Health checks[¶](#health-checks "Permanent link") ------------------------------------------------- You can add a health check to your Dockerfile to ensure that your application is running as expected. This is especially useful when deploying to a cloud provider. `[](#__codelineno-2-1)HEALTHCHECK --interval=30s --timeout=3s \ [](#__codelineno-2-2) CMD curl -f http://localhost:8080/health || exit 1` The following endpoints may be useful when deploying your application: * `/health` or `/healthz` - A health check endpoint that returns a 200 status code if the application is running as expected * `/api/status` - A status endpoint that returns a JSON object with the status of the server HuggingFace - marimo https://docs.marimo.io/guides/deploying/deploying_hugging_face/ Deploy to Hugging Face[¶](#deploy-to-hugging-face "Permanent link") ------------------------------------------------------------------- Hugging Face is a platform that allows you to deploy machine learning models and applications easily. You can deploy a marimo notebook as an interactive web app on Hugging Face Spaces with just a few steps. Deploy[¶](#deploy "Permanent link") ----------------------------------- To deploy your marimo notebook to Hugging Face Spaces: 1. Create a new Space on Hugging Face by forking or copying the following template: [https://huggingface.co/spaces/marimo-team/marimo-app-template/tree/main](https://huggingface.co/spaces/marimo-team/marimo-app-template/tree/main) 2. Replace the contents of the `app.py` file with your marimo notebook. 3. Update the `requirements.txt` file to include any other dependencies your notebook requires. 4. Commit these files to your Space, and Hugging Face will automatically deploy your marimo notebook as an interactive web app. For more detailed instructions and advanced configurations, please refer to the [Hugging Face Spaces documentation](https://huggingface.co/docs/hub/spaces-overview). Ploomber - marimo https://docs.marimo.io/guides/deploying/deploying_ploomber/ Deploy to Ploomber Cloud[¶](#deploy-to-ploomber-cloud "Permanent link") ----------------------------------------------------------------------- For production deployments, you can use Ploomber Cloud. It allows you to deploy marimo in a secure and scalable way. See [deployment instructions here](https://docs.cloud.ploomber.io/en/latest/apps/marimo.html) Public gallery - marimo https://docs.marimo.io/guides/deploying/deploying_public_gallery/ Deploy to our public gallery[¶](#deploy-to-our-public-gallery "Permanent link") ------------------------------------------------------------------------------- If you would like to deploy your application to our [public gallery](https://marimo.io/gallery), please reach out on [Discord](https://marimo.io/discord?ref=docs). You can also easily share your notebooks on the public web using [WASM notebooks](https://docs.marimo.io/guides/wasm/), which run entirely in the browser, no backend required. Railway - marimo https://docs.marimo.io/guides/deploying/deploying_railway/ Deploy to Railway[¶](#deploy-to-railway "Permanent link") --------------------------------------------------------- Railway is a platform that allows you to deploy Dockerize containers easily. Using this pre-built template, Railway will deploy a single-instance marimo edit server with persistent storage in a few clicks. Deploy[¶](#deploy "Permanent link") ----------------------------------- nginx - marimo https://docs.marimo.io/guides/deploying/deploying_nginx/ Deploy with nginx[¶](#deploy-with-nginx "Permanent link") --------------------------------------------------------- nginx is a popular web server that can be used as a reverse proxy for web applications. This guide will show you how to deploy marimo behind an nginx reverse proxy. Prerequisites[¶](#prerequisites "Permanent link") ------------------------------------------------- * A marimo notebook or app that you want to deploy * nginx installed on your server * Basic understanding of nginx configuration Configuration[¶](#configuration "Permanent link") ------------------------------------------------- Create a new configuration file in `/etc/nginx/conf.d/` (e.g., `marimo.conf`): `[](#__codelineno-0-1)server { [](#__codelineno-0-2) server_name your-domain.com; [](#__codelineno-0-3) [](#__codelineno-0-4) location / { [](#__codelineno-0-5) proxy_set_header Host $host; [](#__codelineno-0-6) proxy_set_header X-Real-IP $remote_addr; [](#__codelineno-0-7) proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; [](#__codelineno-0-8) proxy_set_header X-Forwarded-Proto $scheme; [](#__codelineno-0-9) proxy_pass http://127.0.0.1:2718; [](#__codelineno-0-10) [](#__codelineno-0-11) # Required for WebSocket support [](#__codelineno-0-12) proxy_http_version 1.1; [](#__codelineno-0-13) proxy_set_header Upgrade $http_upgrade; [](#__codelineno-0-14) proxy_set_header Connection "upgrade"; [](#__codelineno-0-15) proxy_read_timeout 600; [](#__codelineno-0-16) } [](#__codelineno-0-17) [](#__codelineno-0-18) # Optional: Serve static files [](#__codelineno-0-19) location /static/ { [](#__codelineno-0-20) alias /path/to/your/static/files/; [](#__codelineno-0-21) } [](#__codelineno-0-22)}` Breaking it down[¶](#breaking-it-down "Permanent link") ------------------------------------------------------- * `server_name`: Replace with your domain name * `proxy_pass`: Points to your marimo application (default port is 2718) * WebSocket support: The following lines are required for marimo to function properly: `[](#__codelineno-1-1)proxy_http_version 1.1; [](#__codelineno-1-2)proxy_set_header Upgrade $http_upgrade; [](#__codelineno-1-3)proxy_set_header Connection "upgrade";` * `proxy_read_timeout`: Increased to 600 seconds to handle long-running operations Running your application[¶](#running-your-application "Permanent link") ----------------------------------------------------------------------- 1. Start your marimo application: `[](#__codelineno-2-1)marimo run app.py --host 127.0.0.1 --port 2718` 2. Test your nginx configuration: 3. Reload nginx to apply changes: Your marimo application should now be accessible at your domain. SSL/HTTPS[¶](#sslhttps "Permanent link") ---------------------------------------- For production deployments, it's recommended to use HTTPS. You can use [Certbot](https://certbot.eff.org/) to automatically configure SSL with Let's Encrypt certificates. Common Issues[¶](#common-issues "Permanent link") ------------------------------------------------- ### Kernel Not Found[¶](#kernel-not-found "Permanent link") If you see a "kernel not found" error, ensure that: 1. WebSocket support is properly configured in your nginx configuration 2. The proxy headers are correctly set 3. Your marimo application is running and accessible at the specified proxy\_pass address Prebuilt containers - marimo https://docs.marimo.io/guides/deploying/prebuilt_containers/ marimo provides prebuilt containers for running a marimo server. You can find the containers and tags on [marimo's GitHub packages page](https://github.com/marimo-team/marimo/pkgs/container/marimo). We provide the following variants: * `marimo:latest` - The latest version of marimo * `marimo:latest-data` - The latest version of marimo with `marimo[recommended,lsp]`, `altair`, `pandas`, and `numpy` preinstalled. * `marimo:latest-sql` - The latest version of marimo with `marimo[recommended,lsp,sql]` preinstalled. or any particular version of marimo; for example, `marimo:0.8.3`, `marimo:0.8.3-data`, `marimo:0.8.3-sql`. Each container is built on `3.13-slim`, but if you'd like to see different configurations, please file an issue or submit a PR! Running locally[¶](#running-locally "Permanent link") ----------------------------------------------------- To run the container locally, you can use the following command: `[](#__codelineno-0-1)docker run -p 8080:8080 -it ghcr.io/marimo-team/marimo:latest-sql` Use in a Dockerfile[¶](#use-in-a-dockerfile "Permanent link") ------------------------------------------------------------- To use a prebuilt container in a Dockerfile, you can use the following command: `[](#__codelineno-1-1)FROM ghcr.io/marimo-team/marimo:latest-sql [](#__codelineno-1-2)[](#__codelineno-1-3)# Install any additional dependencies here [](#__codelineno-1-4)[](#__codelineno-1-5)CMD ["marimo", "edit", "--no-token", "-p", "8080", "--host", "0.0.0.0"]` Programmatic - marimo https://docs.marimo.io/guides/deploying/programmatically/ Running the marimo backend programmatically[¶](#running-the-marimo-backend-programmatically "Permanent link") ------------------------------------------------------------------------------------------------------------- marimo can be run programmatically using the `marimo` module. This is useful when you want to run marimo as part of a larger application or when you need to customize the behavior of marimo (e.g. middleware, custom error handling, authentication, routing, etc). FastAPI Example[¶](#fastapi-example "Permanent link") ----------------------------------------------------- Here's an example of how you can run a marimo application programmatically using FastAPI: `[](#__codelineno-0-1)from typing import Annotated, Callable, Coroutine [](#__codelineno-0-2)from fastapi.responses import HTMLResponse, RedirectResponse [](#__codelineno-0-3)import marimo [](#__codelineno-0-4)from fastapi import FastAPI, Form, Request, Response [](#__codelineno-0-5) [](#__codelineno-0-6)[](#__codelineno-0-7)# Create a marimo asgi app [](#__codelineno-0-8)server = ( [](#__codelineno-0-9) marimo.create_asgi_app() [](#__codelineno-0-10) .with_app(path="", root="./pages/index.py") [](#__codelineno-0-11) .with_app(path="/dashboard", root="./pages/dashboard.py") [](#__codelineno-0-12) .with_app(path="/sales", root="./pages/sales.py") [](#__codelineno-0-13)) [](#__codelineno-0-14)[](#__codelineno-0-15)# Create a FastAPI app [](#__codelineno-0-16)app = FastAPI() [](#__codelineno-0-17)[](#__codelineno-0-18)app.add_middleware(auth_middleware) [](#__codelineno-0-19)app.add_route("/login", my_login_route, methods=["POST"]) [](#__codelineno-0-20)[](#__codelineno-0-21)app.mount("/", server.build()) [](#__codelineno-0-22)[](#__codelineno-0-23)# Run the server [](#__codelineno-0-24)if __name__ == "__main__": [](#__codelineno-0-25) import uvicorn [](#__codelineno-0-26) [](#__codelineno-0-27) uvicorn.run(app, host="localhost", port=8000)` For a more complete example, see the [FastAPI example](https://github.com/marimo-team/marimo/tree/main/examples/frameworks/fastapi). Note that when run in this mode, marimo will serve its static assets under the name of the notebook (in the example above, that would be `http://hostname//assets/`). If you are using custom authorization middleware, skip authentication for these assets to avoid server round-trips. There are _many_ of them. Dynamic directory[¶](#dynamic-directory "Permanent link") --------------------------------------------------------- If you'd like to create a server to dynamically load marimo notebooks from a directory, you can use the `with_dynamic_directory` method. This is useful if the contents of the directory change often, such as a directory of notebooks for a dashboard, without restarting the server. `[](#__codelineno-1-1)server = ( [](#__codelineno-1-2) marimo.create_asgi_app() [](#__codelineno-1-3) .with_dynamic_directory(path="/dashboard", directory="./notebooks") [](#__codelineno-1-4))` If the notebooks in the directory are expected to be static, it is better to use the `with_app` method and loop through the directory contents. `[](#__codelineno-2-1)from pathlib import Path [](#__codelineno-2-2)server = marimo.create_asgi_app() [](#__codelineno-2-3)app_names: list[str] = [] [](#__codelineno-2-4)[](#__codelineno-2-5)notebooks_dir = Path(__file__).parent / "notebooks" [](#__codelineno-2-6)[](#__codelineno-2-7)for filename in sorted(notebooks_dir.iterdir()): [](#__codelineno-2-8) if filename.suffix == ".py": [](#__codelineno-2-9) app_name = filename.stem [](#__codelineno-2-10) server = server.with_app(path=f"/{app_name}", root=filename) [](#__codelineno-2-11) app_names.append(app_name)` Accessing Request Data[¶](#accessing-request-data "Permanent link") ------------------------------------------------------------------- Inside your marimo notebooks, you can access the current request data using `mo.app_meta().request`. This is particularly useful when implementing authentication or accessing user data. `[](#__codelineno-3-1)import marimo as mo [](#__codelineno-3-2)[](#__codelineno-3-3)# Access request data in your notebook [](#__codelineno-3-4)request = mo.app_meta().request [](#__codelineno-3-5)if request and request.user and request.user["is_authenticated"]: [](#__codelineno-3-6) content = f"Welcome {request.user['username']}!" [](#__codelineno-3-7)else: [](#__codelineno-3-8) content = "Please log in" [](#__codelineno-3-9)[](#__codelineno-3-10)mo.md(content)` ### Authentication Middleware Example[¶](#authentication-middleware-example "Permanent link") Here's an example of how to implement authentication middleware that populates `request.user`: `[](#__codelineno-4-1)from starlette.middleware.base import BaseHTTPMiddleware [](#__codelineno-4-2)from starlette.requests import Request [](#__codelineno-4-3)[](#__codelineno-4-4)class AuthMiddleware(BaseHTTPMiddleware): [](#__codelineno-4-5) async def dispatch(self, request: Request, call_next): [](#__codelineno-4-6) # Add user data to the request scope [](#__codelineno-4-7) # This will be accessible via mo.app_meta().request.user [](#__codelineno-4-8) request.scope["user"] = { [](#__codelineno-4-9) "is_authenticated": True, [](#__codelineno-4-10) "username": "example_user", [](#__codelineno-4-11) # Add any other user data [](#__codelineno-4-12) } [](#__codelineno-4-13) [](#__codelineno-4-14) # Optional add metadata to the request [](#__codelineno-4-15) request.scope["meta"] = { [](#__codelineno-4-16) "some_key": "some_value", [](#__codelineno-4-17) } [](#__codelineno-4-18) [](#__codelineno-4-19) response = await call_next(request) [](#__codelineno-4-20) return response [](#__codelineno-4-21)[](#__codelineno-4-22)# Add the middleware to your FastAPI app [](#__codelineno-4-23)app.add_middleware(AuthMiddleware)` The `request` object provides access to: * `request.headers`: Request headers * `request.cookies`: Request cookies * `request.query_params`: Query parameters * `request.path_params`: Path parameters * `request.user`: User data added by authentication middleware * `request.url`: URL information including path, query parameters * `request.meta`: Metadata added by your custom middleware ### Documenting and Validating Query Parameters[¶](#documenting-and-validating-query-parameters "Permanent link") When mounted apps accept [query parameters](https://docs.marimo.io/api/query_params/), it can be helpful to declare, validate, and document them with the help of a [Pydantic model](https://fastapi.tiangolo.com/tutorial/query-param-models/). If a marimo app called `notebooks/items.py` is mounted to `/items`, declaring an endpoint with the same route will take the query parameters through Pydantic model validation first, then redirect to the marimo endpoint. `[](#__codelineno-5-1)# src/main.py [](#__codelineno-5-2)from fastapi import FastAPI, Request, Query [](#__codelineno-5-3)from fastapi.responses import RedirectResponse [](#__codelineno-5-4)from marimo import create_asgi_app [](#__codelineno-5-5)from pathlib import Path [](#__codelineno-5-6)from pydantic import BaseModel, Field [](#__codelineno-5-7)from typing import Annotated, Literal [](#__codelineno-5-8)from urllib.parse import urlencode [](#__codelineno-5-9) [](#__codelineno-5-10)[](#__codelineno-5-11)app = FastAPI() [](#__codelineno-5-12) [](#__codelineno-5-13)[](#__codelineno-5-14)class FilterParams(BaseModel): [](#__codelineno-5-15) limit: int = Field(100, gt=0, le=100) [](#__codelineno-5-16) offset: int = Field(0, ge=0) [](#__codelineno-5-17) order_by: Literal["created_at", "updated_at"] = "created_at" [](#__codelineno-5-18) tags: list[str] = [] [](#__codelineno-5-19) [](#__codelineno-5-20)[](#__codelineno-5-21)@app.get("/items") [](#__codelineno-5-22)async def marimo_items( [](#__codelineno-5-23) request: Request, filter_query: Annotated[FilterParams, Query()] [](#__codelineno-5-24)): [](#__codelineno-5-25) query_params = urlencode(filter_query.model_dump(), doseq=True) [](#__codelineno-5-26) return RedirectResponse(url=f"/items/?{query_params}") [](#__codelineno-5-27) [](#__codelineno-5-28)[](#__codelineno-5-29)server = create_asgi_app(include_code=True, quiet=False) [](#__codelineno-5-30)notebooks_dir = Path(__file__).parent.parent / "notebooks" [](#__codelineno-5-31)[](#__codelineno-5-32)for filename in notebooks_dir.iterdir(): [](#__codelineno-5-33) if filename.suffix == ".py": [](#__codelineno-5-34) app_name = filename.stem [](#__codelineno-5-35) server = server.with_app(path=f"/{app_name}", root=filename) [](#__codelineno-5-36) [](#__codelineno-5-37)[](#__codelineno-5-38)app.mount("/", server.build())` Under the Hood[¶](#under-the-hood "Permanent link") --------------------------------------------------- Behind the scenes, in this mode, marimo is spinning up a new computational kernel in a separate sub-thread (same process) for each new session / app created. There are a few implications of this from a performance and reliability perspective: * If you are running multiple instances of this same server for load balancing, you will need to use sticky sessions in your load balancer to ensure that the same client gets the same kernel each time. * Similarly, attempting to run multiple instances of the same FastAPI process (a common approach with Python web services) on the same node will not work reliably, since only one of them will actually be running the kernel. In summary, there are limitations to how far the approach described here can horizontally scale, so we recommend scaling vertically first. In other words, increase the container CPU/Memory specs before increasing the number of container instances. Scheduled jobs - marimo https://docs.marimo.io/guides/deploying/scheduled/ Running marimo notebooks as scheduled jobs[¶](#running-marimo-notebooks-as-scheduled-jobs "Permanent link") ----------------------------------------------------------------------------------------------------------- marimo notebooks are stored as Python files, so any system that can schedule a Python script can schedule a marimo notebook. This includes [cron](https://en.wikipedia.org/wiki/Cron), [airflow](https://airflow.apache.org/) or [prefect](https://www.prefect.io/). You can even [pass variables](https://docs.marimo.io/guides/scripts/?h=command+line) from the command line to marimo notebooks, which makes them well-suited to this use-case. Github Actions[¶](#github-actions "Permanent link") --------------------------------------------------- As an alternative to using [cron](https://en.wikipedia.org/wiki/Cron) directly, you might be interested in running scheduled marimo notebooks as part of your [Github actions](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule) workflow. You can use the code below as a starting point. Note that this example assumes you're using [inline dependencies](https://docs.marimo.io/guides/package_management/inlining_dependencies/). `[](#__codelineno-0-1)name: Run marimo notebook every day at 09:00 [](#__codelineno-0-2)[](#__codelineno-0-3)on: [](#__codelineno-0-4) schedule: '0 9 * * *' [](#__codelineno-0-5)jobs: [](#__codelineno-0-6) scheduled: [](#__codelineno-0-7)jobs: [](#__codelineno-0-8) run-marimo: [](#__codelineno-0-9) runs-on: ubuntu-latest [](#__codelineno-0-10) [](#__codelineno-0-11) steps: [](#__codelineno-0-12) - name: Checkout repository [](#__codelineno-0-13) uses: actions/checkout@v4 [](#__codelineno-0-14) [](#__codelineno-0-15) - name: Set up Python [](#__codelineno-0-16) uses: actions/setup-python@v5 [](#__codelineno-0-17) with: [](#__codelineno-0-18) python-version: '3.11' [](#__codelineno-0-19) [](#__codelineno-0-20) - name: Install uv [](#__codelineno-0-21) uses: astral-sh/setup-uv@v7 [](#__codelineno-0-22) with: [](#__codelineno-0-23) version: "latest" [](#__codelineno-0-24) [](#__codelineno-0-25) - name: Use uv to run notebook as normal script [](#__codelineno-0-26) run: | [](#__codelineno-0-27) uv run path/to/marimo_notebook.py` Alternatives[¶](#alternatives "Permanent link") ----------------------------------------------- For tools like Airflow and Prefect, you can also choose to reuse parts of a marimo notebook in larger Python batch jobs. Check the [docs on reusing functions](https://docs.marimo.io/guides/reusing_functions/) or [this Prefect tutorial on YouTube](https://www.youtube.com/watch?v=CvSbGTFCpF4) if you're interested in that. For Airflow specifically it might make also sense to write a custom operator, see [this tutorial on YouTube](https://www.youtube.com/watch?v=ITuUYW14ToA) for more details. Alternatively, you may be interested in having specific cells in marimo run on an automated schedule as you have the notebook open. The simplest way to do that is to use the [mo.ui.refresh](https://docs.marimo.io/api/inputs/refresh/#marimo.ui.refresh) widget to manually specify how often a cell needs to rerun. Finally, if you have very custom needs, you can always use third party Python libraries (like [schedule](https://schedule.readthedocs.io/en/stable/index.html)) to set up something bespoke from your own code. Configuration - marimo https://docs.marimo.io/guides/configuration/ marimo offers two types of configuration: User Configuration and App Configuration. Both can be easily managed through the Settings menu in the marimo editor. App Configuration[¶](#app-configuration "Permanent link") --------------------------------------------------------- App Configuration is specific to each notebook and is stored in the `notebook.py` file. This allows you to customize various aspects of your notebook, including: * Notebook width * Notebook title * [Custom CSS](https://docs.marimo.io/guides/configuration/theming/) * [Custom HTML Head](https://docs.marimo.io/guides/configuration/html_head/) * Automatically download HTML snapshots Configure these settings through the notebook menu (⚙️) in the top-right corner. User Configuration[¶](#user-configuration "Permanent link") ----------------------------------------------------------- User Configuration applies globally across all marimo notebooks and is stored in a `$XDG_CONFIG_HOME/marimo/marimo.toml` file. While you can edit the `$XDG_CONFIG_HOME/marimo/marimo.toml` file directly, we recommend using the marimo UI for a more user-friendly experience. You can customize the following settings: * [Runtime](https://docs.marimo.io/guides/configuration/runtime_configuration/), including whether notebooks autorun * [Hotkeys](https://docs.marimo.io/guides/editor_features/hotkeys/) * Completion (auto-completion, AI copilot, etc.) * Display (theme, font size, output placement, etc.) * Autosave * [Package management](https://docs.marimo.io/guides/editor_features/package_management/#package-management) * Server settings * [VIM keybindings](https://docs.marimo.io/guides/editor_features/overview/#vim-keybindings) * Formatting settings * [AI assistance](https://docs.marimo.io/guides/editor_features/ai_completion/) * [Snippets](https://docs.marimo.io/guides/configuration/snippets/) * Experimental features ### User configuration file[¶](#user-configuration-file "Permanent link") marimo searches for the `.marimo.toml` file in the following order: 1. Current directory 2. Parent directories (moving up the tree) 3. Home directory (`~/.marimo.toml`) 4. [XDG](https://xdgbasedirectoryspecification.com/) directory (`~/.config/marimo/marimo.toml` or `$XDG_CONFIG_HOME/marimo/marimo.toml`) If no `.marimo.toml` file is found, marimo creates one for you in an XDG config compliant way. To view your current configuration and locate the config file, run: To describe the user configuration options, run: ### Overriding settings with pyproject.toml[¶](#overriding-settings-with-pyprojecttoml "Permanent link") You can override user configuration settings with a `pyproject.toml` file. This is useful for sharing configurations across teams or ensuring consistency across notebooks. You must edit the `pyproject.toml` file directly to override settings. For example, the following `pyproject.toml` file overrides the `autosave` setting in the user configuration: pyproject.toml `[](#__codelineno-2-1)[tool.marimo.formatting] [](#__codelineno-2-2)line_length = 120 [](#__codelineno-2-3)[](#__codelineno-2-4)[tool.marimo.display] [](#__codelineno-2-5)default_width = "full" [](#__codelineno-2-6)[](#__codelineno-2-7)[tool.marimo.runtime] [](#__codelineno-2-8)default_sql_output = "native"` You can override any user configuration setting in this way. To find these settings run `marimo config show`. Overridden settings Settings overridden in `pyproject.toml` or script metadata cannot be changed through the marimo editor's settings menu. Any changes made to overridden settings in the editor will not take effect. ### Script Metadata Configuration[¶](#script-metadata-configuration "Permanent link") You can also configure marimo settings directly in your notebook files using script metadata (PEP 723). Add a `script` block at the top of your notebook: `[](#__codelineno-3-1)# /// script [](#__codelineno-3-2)# [tool.marimo.runtime] [](#__codelineno-3-3)# auto_instantiate = false [](#__codelineno-3-4)# on_cell_change = "lazy" [](#__codelineno-3-5)# [tool.marimo.display] [](#__codelineno-3-6)# theme = "dark" [](#__codelineno-3-7)# cell_output = "below" [](#__codelineno-3-8)# ///` Configuration precedence Script metadata configuration has the highest precedence, followed by `pyproject.toml` configuration, then user configuration: **Script config > pyproject.toml config > user config** Environment Variables[¶](#environment-variables "Permanent link") ----------------------------------------------------------------- marimo supports the following environment variables for advanced configuration: | Environment Variable | Description | Default Value | | --- | --- | --- | | `MARIMO_OUTPUT_MAX_BYTES` (deprecated, use `pyproject.toml`) | Maximum size of output that marimo will display. Outputs larger than this will be truncated. | 8,000,000 (8MB) | | `MARIMO_STD_STREAM_MAX_BYTES` (deprecated, use `pyproject.toml`) | Maximum size of standard stream (stdout/stderr) output that marimo will display. Outputs larger than this will be truncated. | 1,000,000 (1MB) | | `MARIMO_SKIP_UPDATE_CHECK` | If set to "1", marimo will skip checking for updates when starting. | Not set | | `MARIMO_SQL_DEFAULT_LIMIT` | Default limit for SQL query results. If not set, no limit is applied. | Not set | ### Tips[¶](#tips "Permanent link") * The `.marimo.toml` file can be version controlled to share configurations across teams * App configurations can be committed with notebooks to ensure consistent appearance Online playground - marimo https://docs.marimo.io/guides/publishing/playground/ Our [online playground](https://marimo.app/) lets you create and share marimo notebooks for free, without creating an account. Playground notebooks are great for embedding in other web pages — all the embedded notebooks in marimo's own docs are playground notebooks. They are also great for sharing via links. **Try our playground!** Just navigate to [https://marimo.new](https://marimo.new/). WebAssembly notebooks only Currently, the online playground only allows the creation of [WebAssembly notebooks](https://docs.marimo.io/guides/wasm/). These are easy to share and embed in other web pages, but have some limitations in packages and performance. _The notebook embedded below is a playground notebook!_ Creating and sharing playground notebooks[¶](#creating-and-sharing-playground-notebooks "Permanent link") --------------------------------------------------------------------------------------------------------- Playground notebooks run at [marimo.app](https://marimo.app/). ### New notebooks[¶](#new-notebooks "Permanent link") To create a new playground notebook, visit [https://marimo.new](https://marimo.new/). Think of [marimo.new](https://marimo.new/) as a scratchpad for experimenting with code, data, and models and for prototyping tools, available to you at all times and on all devices. Saving playground notebooks When you save a WASM notebook, a copy of your code is saved to your web browser's local storage. When you return to [marimo.app](https://marimo.app/), the last notebook you worked on will be re-opened. You can also click a button to save your notebook to the [Community Cloud](https://docs.marimo.io/guides/publishing/community_cloud/). At [marimo.app](https://marimo.app/), save your notebook and then click the `Create permalink` button to generate a shareable permalink to your notebook. Please be aware that marimo permalinks are publicly accessible. ### Open notebooks hosted on GitHub[¶](#open-notebooks-hosted-on-github "Permanent link") To open notebooks hosted on GitHub in the playground, just navigate to `https://marimo.app/path/to/notebook.py`. For example: [https://marimo.app/github.com/marimo-team/marimo/blob/main/examples/ui/slider.py](https://marimo.app/github.com/marimo-team/marimo/blob/main/examples/ui/slider.py). Use our bookmarklet! For a convenient way to create notebooks from GitHub, drag and drop the following button to your bookmarks bar: Open in marimo Clicking the bookmark when you are viewing a notebook will open it in [marimo.app](https://marimo.app/). From Jupyter notebooks You can also create Playground notebooks from Jupyter notebooks hosted on GitHub. marimo will attempt to automatically convert the notebook to a marimo notebook. #### Including data files[¶](#including-data-files "Permanent link") Notebooks created from GitHub links have the entire contents of the repository mounted into the notebook's filesystem. This lets you work with files using regular Python file I/O! When constructing paths to data files, make sure to use [`mo.notebook_dir()`](https://docs.marimo.io/api/miscellaneous/#marimo.notebook_dir " marimo.notebook_dir") to ensure that paths work both locally and in the playground. #### Open in marimo badge[¶](#open-in-marimo-badge "Permanent link") Include an "open in marimo" badge in your README to link to playground notebooks hosted on GitHub: MarkdownHTML Replace `GITHUB_URL` with the URL to a notebook on GitHub. `[](#__codelineno-0-1)[![Open with marimo](https://marimo.io/shield.svg)](https://marimo.app/GITHUB_URL)` Replace `GITHUB_URL` with the URL to a notebook on GitHub. `[](#__codelineno-1-1) [](#__codelineno-1-2) Open in marimo [](#__codelineno-1-3)` ### Creating playground notebooks from local notebooks[¶](#creating-playground-notebooks-from-local-notebooks "Permanent link") In the marimo editor's notebook action menu, use `Share > Create WebAssembly link` to get a `marimo.app/...` URL representing your notebook: WASM notebooks come with common Python packages installed, but you may need to [install additional packages using micropip](https://docs.marimo.io/guides/wasm/#supported-packages). The obtained URL encodes your notebook code as a parameter, so it can be quite long. If you want a URL that's easier to share, you can [create a shareable permalink](#share-via-links). Configuration[¶](#configuration "Permanent link") ------------------------------------------------- Your `marimo.app` URLs can be configured using the following parameters. ### Read-only mode[¶](#read-only-mode "Permanent link") To view a notebook in read-only mode, with code cells locked, append `&mode=read` to your URL's list of query parameters (or `?mode=read` if your URL doesn't have a query string). Example: * `https://marimo.app/l/83qamt?mode=read` To hide the `marimo.app` header, append `&embed=true` to your URL's list of query parameters (or `?embed=true` if your URL doesn't have a query string). Example: * `https://marimo.app/l/83qamt?embed=true` * `https://marimo.app/l/83qamt?mode=read&embed=true` See the [section on embedding](#embedding-in-other-web-pages) for examples of how to embed marimo notebooks in your own webpages. ### Excluding code[¶](#excluding-code "Permanent link") By default, WASM notebooks expose your Python code to viewers. If you've enabled read-only mode, you can exclude code with `&include-code=false`. If you want to include code but have it be hidden by default, use the parameter `&show-code=false`. A sufficiently determined user would still be able to obtain your code, so **don't** think of this as a security feature; instead, think of it as an aesthetic or practical choice. Embedding in other web pages[¶](#embedding-in-other-web-pages "Permanent link") ------------------------------------------------------------------------------- WASM notebooks can be embedded into other webpages using the HTML `` Showing editor controls To show editor controls (such as panels icons and the run button), use the query parameter `show-chrome=true` ### Embedding an existing notebook[¶](#embedding-an-existing-notebook "Permanent link") To embed existing marimo notebooks into a webpage, first, [obtain a URL to your notebook](#creating-and-sharing-playground-notebooks), then put it in an iframe. `[](#__codelineno-3-1)` ### Embedding an existing notebook in read-only mode[¶](#embedding-an-existing-notebook-in-read-only-mode "Permanent link") You can optionally render embedded notebooks in read-only mode by appending `&mode=read` to your URL. `[](#__codelineno-4-1)` ### Embedding from code[¶](#embedding-from-code "Permanent link") You can also embed marimo notebook from its string representation (i.e., the notebook file's code), using the `code` query parameter: `[](#__codelineno-5-1)https://marimo.app?embed=true&show-chrome=false&code=` where `` is the notebook code URI encoded. For example, in JavaScript: `[](#__codelineno-6-1)encodeURIComponent(notebookCode)` #### Using lz compression for large notebooks[¶](#using-lz-compression-for-large-notebooks "Permanent link") When using the `code` query parameter, your notebooks must be no greater than `14 KB`. For large notebooks, `marimo.app` supports lz-compressed notebook code with a URL hash. For example, in JavaScript, you can use the [`lz-string`](https://www.npmjs.com/package/lz-string) package: `` [](#__codelineno-7-1)import { compressToEncodedURIComponent } from "lz-string"; [](#__codelineno-7-2)[](#__codelineno-7-3)const url = `https://marimo.app/#code/${compressToEncodedURIComponent(code)}` `` #### MDX[¶](#mdx "Permanent link") For example, if you are using MDX, you can use the following snippet: ``[](#__codelineno-8-1)const MdxNotebook = (props: { code: string }) => { [](#__codelineno-8-2) return ( [](#__codelineno-8-3)