Function convert

marimo/_cli/convert/commands.py:34–142

r"""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 strip

(
    filename: str,
    output: Path | None,
)

    ),
)
def convert(
    filename: str,
    output: Path | None,
) -> None:
    r"""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}
      x = 1 + 2
      print(x)
      ```
    - 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

    You can also pass global flags to the main marimo command.
    For example, use `-q` to suppress output or `-y`
    to automatically accept all prompts of the command.

        marimo -q -y convert script.py -o your_nb.py

    After conversion:

        marimo edit your_nb.py

    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.
    """

    ext = Path(filename).suffix
    if ext not in (".ipynb", ".md", ".qmd", ".py"):
        raise click.UsageError("File must be an .ipynb, .md, or .py file")