Prevent accidental overwrites and converter for non-marimo Python scripts

[manzt]

Previously, marimo edit script.py would silently overwrite any Python file, potentially destroying user code (link).

#5677 introduced a prompt asking users to confirm before overwriting invalid files. This PR takes a stronger stance by making marimo edit error for non-marimo Python files and providing a conversion path.

It introduces two key changes:

1. Protection against accidental overwrites: marimo edit now errors when attempting to open a non-marimo Python file, rather than prompting for confirmation. Users are directed to use marimo convert instead.

2. Python script conversion support: marimo convert script.py now supports converting regular Python scripts to marimo notebooks. The converter:

   • Detects and converts py:percent format if used (requires jupytext), otherwise uses a single marimo cell
   • Transforms if __name__ == "__main__": blocks into _main_() functions to maintain marimo's variable scoping
   • Preserves file headers (docstrings/comments)

Importantly the notebook pipeline reuses the ipynb converter transformations for multiple cells.

Running marimo edit regular_script.py now shows:

Error: Python script not recognized as a marimo notebook.

  Tip: Try converting with

    marimo convert regular_script.py -o regular_script_nb.py

  then open with marimo edit regular_script_nb.py

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
marimo-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 29, 2025 2:46pm

[dmadisetti]

Oh no, potentially closed by #5677

[dmadisetti]

There's actually a fair bit of other logic in here. Will do a review on merge res if you want to keep it open

[manzt]

if it makes the review easier, i'm happy to break into two separate PRs:

• one that checks and errors on marimo edit unknown_py_script.py
• one that add marimo convert and updates the error message from above with a Tip

[manzt]

Most of the logic is in the second commit for adding a new converter. The error is just adding another violation that we error on inside marimo edit.

[dmadisetti]

I think splitting these out make sense, will make the merge res easier

[willingc]

Thanks @manzt @dmadisetti. Simple is fine by me. It was a bit of a surprise when it happened. As an FYI, I could see folks wanting to be able to bulk convert a directory of .py files to marimo notebooks, such as when creating examples for docs, which is how I discovered the behavior.

[dmadisetti]

Thanks @willingc, hope you didn't lose any important files 😬
The bulk util does make sense, a general pattern matching, or repeating arg might be reasonable

[mscolnick]

calling it unknown python script feels a bit weird to me. especially if we introduce marimo convert pypercent, this will conflict with this code path. and in future, if/when we do add marimo convert pypercent, we can treat these "unknown scripts" as just a pypercent with 1 cell.

[willingc]

@dmadisetti I didn't lose anything since everything is under version control.

I agree with @mscolnick "unknown python script" is odd phrasing to a user. If everything is a .py file, it should behave like a .py file whether or not it is a marimo notebook.

Ultimately, I would love to see (some of which you already have):

• A regular .py file (code or script) opened in a marimo notebook (going to call it .mpy) without data loss
• A regular .py file (code or script) converted to a marimo notebook (.mpy)
• A marimo notebook (.mpy) stripped and converted to a regular .py file without marimo code included (IMHO, cleaner for using in a pipeline)
• A Jupyter notebook (.ipynb) converted to a marimo notebook (.mpy) with cells similar to the initial Jupyter notebook
• A marimo notebook (.mpy) converted to a Jupyter notebook (.ipynb)
• A marimo notebook exportable as a PDF
• Bonus points: being able to do that using pandoc 😉

[willingc]

I love the effort here. I would be fine with a simple warning that the .py file does not include marimo notebook code. See this link on creating or converting... would be fine short term.

[manzt]

I might followup to make confirm non-blocking in non-tty contexts.

I don't think these changes introduce any new interactive code paths, unless I'm misunderstanding. Are you referring to improving the existing overwrite confirmation to be non-blocking in non-TTY contexts?

[dmadisetti]

I don't think these changes introduce any new interactive code paths, unless I'm misunderstanding. Are you referring to improving the existing overwrite confirmation to be non-blocking in non-TTY contexts?

Yes, related to this PR, but yes nothing this code explicitly touches

[dmadisetti]

Cool! See comment. I can still follow up in a PR, but let's decide and get it in before next release.
I'm happy with this PR, but LMK if you have thoughts and want to adjust the flow here

[dmadisetti]

Thanks for the rebase.
This might be dead code now? Either way the ideal behavior for molab is:

if not tty and invalid: continue # as normal (regardless of .py ending)

If this is too dangerous, we can hide behind a another flag. An auto convert flag could be reasonable

if invalid and autoconvert: convert and continue

[manzt]

The above condition is:

if status == "invalid" and filename.endswith(".py"):

I assume non-Python files could also result in an invalid notebook status, making this code not dead in that context? I don't know the molab context well enough and trust whatever you think.