skilld
All skills
marimo-team avatar

/jupyter-to-marimo

@6454470
by marimomarimo-team/skills173 stars
15

Convert a Jupyter notebook (.ipynb) to a marimo notebook (.py).

Ask your Agent

Use this Skill: https://skilld.dev/gh/marimo-team/skills/jupyter-to-marimo

This session only. Nothing lands on disk.

SKILL.md

≈21 tokens always: the name and description. ≈674 when used: this file. ≈2.4k more on demand in 2 files.

Converting Jupyter Notebooks to Marimo

Convert first

Important: Run the converter before you read the source notebook:

uvx marimo convert <notebook.ipynb> -o <notebook.py>

Read the .ipynb file only if conversion fails or the generated file omits required information. Treat the generated file as a first draft.

Run this command after conversion and after substantial edits:

uvx marimo check <notebook.py>

Review the conversion

  • Verify all required packages in the PEP 723 metadata. The converter can miss some package-installation forms.
  • Remove residual installation cells and stale installation prose. Add version constraints only when required.
  • Use --sandbox when a notebook uses PEP 723 metadata.
  • Preserve the purpose and intended workflow of the source notebook.
  • Arrange cells for presentation. marimo determines execution order from variable definitions and references.
  • A cell can appear before a cell that defines its input.
  • Merge or split cells when the current boundaries reduce clarity.
  • Remove redundant Jupyter artifacts, such as unnecessary display() calls.
  • Review converted magic commands. Keep valid conversions, and resolve comments that report unsupported magics.
  • Put the value to render in the final expression of each cell.
  • Keep added UI and helper functions proportional to the notebook purpose.
  • Replace interactive input methods that wait for terminal input or do not work in the target interface. Use suitable UI controls, script parameters, or environment values.
  • Do not print, log, or save secrets. Consider EnvConfig for multiple environment values.
  • Identify expensive work and external side effects. If work must wait, gate it with mo.stop() and a suitable UI element.
  • Use a form if the user must submit multiple values together.
  • Define downstream values after the gate so the dependency graph defers dependent cells.
  • Present useful results with simple native components. Add live refresh only when the intended workflow requires it.
  • For ipywidgets, read references/widgets.md.
  • For LaTeX and MathJax, read references/latex.md.

Validate the result

  • Run marimo check again after all edits.
  • Run the notebook in each intended mode. Confirm that it has the intended behavior.
  • When practical, open the source and converted notebooks side by side and invite the user to review.
  • Compare content, controls, outputs, and workflow. Cell order and layout can differ.
  • Inspect changed files for secrets, generated data, caches, logs, and other runtime files.

Source: SKILL.md on GitHub

Third-party checks

No alerts17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides a comprehensive guide for converting Jupyter notebooks (.ipynb) to marimo notebooks (.py). It outlines a conversion workflow using the 'marimo' CLI tool, provides mapping tables for LaTeX and UI widgets, and includes best practices for security such as secret management and output validation.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    1/1 file flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 6454470. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Steadyupdated last month

Topics

README badge

README badge for marimo-team/skills

What it does

Converts Jupyter notebooks to marimo notebooks using the `marimo convert` CLI command, then validates and cleans up the output by removing Jupyter artifacts and ensuring compatibility with marimo's cell rendering model. Handles ipywidgets-to-marimo widget migration, LaTeX syntax conversion, and environment variable configuration.

Generated from the current SKILL.md.

Frequently asked

Does this skill handle ipywidgets conversion?
The skill includes a reference mapping ipywidgets to marimo equivalents with patterns for callbacks and linking, but you must manually apply those conversions after running the CLI convert command.
What happens to Jupyter magic commands and display() calls?
The marimo converter may leave these artifacts in place; you need to manually remove or adapt them during the cleanup step, as they don't apply in marimo notebooks.
Do I need to install marimo separately?
No. The skill uses `uvx marimo convert` and `uvx marimo check`, which run marimo without a local install.
Will the converter catch all missing package dependencies?
No. The converter may miss some required packages in the metadata block, so you must review and update the script's package list after conversion.
How does this skill handle LaTeX in notebooks?
The skill provides a reference guide for converting MathJax syntax to KaTeX, which marimo uses, but conversion must be done manually.

Generated from the current SKILL.md. These answers refresh after source changes.