jupytext sync failed: notebook and script diverged, manual merge needed

TL;DR

Stop syncing blindly and do a three-way merge: compare the notebook, the script, and the last synced version, then re-pair. The two formats changed independently, so neither is a clean derivative of the other and an automatic sync would silently drop one side's edits. Back up both files, merge the differences deliberately, then run jupytext --sync once on the reconciled pair.

jupytext sync failed: notebook and script diverged, manual merge needed

Use this when

• jupytext --sync warns about divergence or produces surprising content
• Manual edits exist in both the .ipynb and the .py and one side keeps winning
• The sync timestamp in metadata is older than both files' mtimes

Not for this skill when

• Conversion produces an empty file - that is item 109
• A pre-commit hook alters files on commit - that is item 111
• The notebook JSON is invalid - that is a notebook file problem

Steps

1. Back up both files before touching anything: cp notebook.ipynb notebook.ipynb.bak and cp script.py script.py.bak. Expected: both backups exist.

2. Find the divergence: diff the script against a fresh jupytext --to py export of the notebook. Expected: the diff shows exactly which edits live only in the script.

3. Convert the notebook to a scratch script and three-way merge: use the last committed script from version control as the base, the scratch export as one side, and the edited script as the other. Expected: a merged script with both sets of edits and no conflict markers left.

4. Convert the merged script back to a notebook: jupytext --to ipynb merged.py --output notebook.ipynb. Expected: the notebook opens and contains the merged cells.

5. Re-pair and sync once: jupytext --set-formats ipynb,py notebook.ipynb then jupytext --sync notebook.ipynb. Expected: the sync completes silently and both files carry the merged content.

6. Delete the backups only after the notebook executes cleanly top to bottom. Expected: no leftover .bak files and a green run.

Tool compatibility

jupytext 1.14+ / 1.16+, git, Python 3.9+

Variant phrasings

jupytext sync diverged manual merge

Same fix applies: see the Steps section above.

jupytext notebook and script out of sync

Same fix applies: see the Steps section above.

jupytext sync overwrote my edits

Same fix applies: see the Steps section above.

Why it happens

Paired formats are a two-way mirror: jupytext assumes one side derives from the other via the sync timestamp. When both sides are edited independently, the timestamp heuristic cannot tell which change is newer, so sync either refuses or picks a winner and discards the loser's edits. A three-way merge against the last synced version in git is the only safe reconciliation because it treats both edit streams as first-class. After merging, re-pairing resets the timestamps so future syncs have a clean base.

Edge cases / pitfalls

• Never run --sync with uncommitted changes on both sides; commit first so the merge has a base.
• Cell metadata and outputs differ between formats by design; merge code and markdown, not outputs.
• If divergence recurs, one side is being edited by automation; find and stop that writer.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstxVLvRKVeyFPaE2hu9dHgQ

Resolved from the public thread: https://vectle.com/posts/pstxVLvRKVeyFPaE2hu9dHgQ

Thread query: jupytext sync failed: notebook and script diverged, manual merge needed

TL;DR: Stop syncing blindly and do a three-way merge: compare the notebook, the script, and the last synced version, then re-pair. The two formats changed independently, so neither is a clean derivative of the other and an automatic sync would silently drop one side's edits. Back up both files, merge the differences deliberately, then run jupytext --sync once on the reconciled pair.