使用Jupytext从.py生成.ipynb及PyCharm同步覆盖问题咨询

核心原因：单向转换而非双向同步，Jupytext默认重建逻辑导致覆盖 #

你遇到的问题本质是错误配置了单向文件转换，而非使用Jupytext的双向同步机制，加上文件监视器的循环触发，才出现了互相覆盖的情况：

1. 从.ipynb到.py的反向覆盖
   当你保存.ipynb时，如果监视器只是执行jupytext --to py {file}生成.py，而同时又有另一个监视器监听.py的变化、执行jupytext --to ipynb {file}，就会触发循环：

   • 你修改.ipynb并保存 → 生成新的.py
   • .py的变化触发另一个监视器 → 基于刚生成的.py重建.ipynb
     这时候新生成的.ipynb是完全基于.py的内容（可能丢失你刚在.ipynb里加的markdown、输出或未同步到.py的代码），看起来就像是.py覆盖了刚修改的Notebook。

2. 保存.py时.ipynb被完全替换
   Jupytext默认从.py生成.ipynb时，是完全重建Notebook：它会把.py里的代码转为代码单元格，但不会保留原.ipynb里的输出、自定义markdown单元格（除非你用Jupytext的注释格式对应markdown），也不会合并原Notebook的修改。如果你的监视器只是单向生成.ipynb，自然会把原Notebook的内容全部替换成.py的内容。

3. 为什么从Notebook生成.py正常？
   这是单向的导出操作，没有反向触发的循环，Jupytext会把.ipynb的代码单元格（以及markdown单元格转成注释）写入.py，不会触发反向的.ipynb生成，所以不会出现覆盖。

解决关键：切换到Jupytext的双向同步模式 #

要实现真正的双向同步，需要调整两个核心配置：

1. 给Notebook添加Jupytext同步元数据

在你的.ipynb文件的元数据里添加如下配置（可以通过jupytext --set-formats ipynb,py {file}命令自动添加）：

{
  "jupytext": {
    "formats": "ipynb,py",
    "sync": {
      "at_least_one": true,
      "update_markdown_cells": true,
      "update_code_cells": true
    }
  }
}

这个配置告诉Jupytext：

• 同时维护.ipynb和.py两个格式的文件
• 同步时会更新代码单元格和markdown单元格（markdown会转成.py里的特殊注释）
• 确保至少保留一个文件的修改，避免单向覆盖

2. 修改PyCharm文件监视器的命令

把原来的单向转换命令，改成Jupytext的同步命令：

• 针对.ipynb文件的监视器：
  命令：jupytext
  参数：--sync $FilePath$
  触发条件：仅在文件保存时触发，排除自动生成的文件
• 针对.py文件的监视器：
  命令：jupytext
  参数：--sync $FilePath$
  触发条件：同上

--sync参数是Jupytext专门用于双向同步的命令，它会自动对比两个文件的修改时间和内容，只同步有变化的部分，不会触发循环覆盖。

内容的提问来源于stack exchange，提问作者salomepx