Skip to content

Thumbnails

Generate screenshot-based thumbnail images for notebooks, used by OpenGraph previews and cards in gallery mode.

marimo export thumbnail notebook.py

Output location

By default, thumbnails are written to:

<notebook_dir>/__marimo__/assets/<notebook_stem>/opengraph.png

This is the default OpenGraph thumbnail path used by OpenGraph previews.

Requirements

Requires Playwright

Thumbnail generation uses Playwright and Chromium:

python -m pip install playwright
python -m playwright install chromium

Generate thumbnails

You can generate a thumbnail for a single notebook:

marimo export thumbnail notebook.py

Or generate thumbnails for all notebooks in a directory:

marimo export thumbnail folder/

When you pass a directory, marimo scans it for marimo notebooks and skips non-notebook files (for example README.md).

Execution modes

By default, thumbnails are generated without executing the notebook (fast; no outputs). You can opt into execution if you want outputs included.

marimo export thumbnail notebook.py

marimo export thumbnail --execute notebook.py 

marimo export thumbnail --execute --sandbox notebook.py

Choose a sandbox backend

--sandbox defaults to uv. Use --sandbox=uv or --sandbox=pixi to select the backend explicitly; only the selected tool needs to be installed. Use --no-sandbox to disable sandboxing and dependency prompts.

Sandboxed execution installs dependencies from inline script metadata (PEP 723). See Inlining dependencies.

Each notebook executes in its own process using its inline dependencies. Playwright is installed for the renderer without adding it to notebook dependencies.

Sandbox only applies with execution

--sandbox requires --execute. In --no-execute mode, marimo does not run the notebook, so there are no dependencies to install.

Including code

In --no-execute mode, thumbnails always include code. When using --execute, add --include-code to show code alongside outputs.

Overwriting and custom output paths

If a thumbnail already exists, marimo will skip it by default. To replace existing thumbnails:

marimo export thumbnail --overwrite notebook.py

To write a thumbnail to a specific filename, use --output (single notebook only):

marimo export thumbnail --output thumbnail.png notebook.py

Tuning quality

For OpenGraph previews, the default viewport size is 1200x630. marimo also uses a default --scale 2 so thumbnails are crisp at typical OpenGraph resolutions.

To increase output resolution, increase --scale (max 4):

marimo export thumbnail --scale 3 notebook.py

If thumbnails appear blank or partially rendered, increase --timeout-ms to wait longer before the screenshot:

marimo export thumbnail --timeout-ms 3000 notebook.py

Passing arguments to notebooks

To pass CLI args through to the notebook, separate them with --:

marimo export thumbnail notebook.py -- --foo 123

For more on passing values to notebooks, see Command Line Arguments.