Parameter	Required	Description
`target_notebook`	Yes	Path to .ipynb
`cell_idx`	Yes	0-based cell index
`is_new_cell`	Yes	`true` = new cell, `false` = edit existing
`cell_language`	Yes	`python`, `markdown`, `r`, `sql`, `shell`, `raw`, `other`
`old_string`	Yes	Text to replace (empty for new cells)
`new_string`	Yes	Replacement content

Critical rules:

Set is_new_cell correctly
Include 3-5 lines context in old_string
Cannot delete cells (clear content with new_string="")

Jupytext (Structural Edits)

Setup & Sync

# Pair notebook (one-time)
python -m jupytext --set-formats ipynb,py:percent notebook.ipynb

# Always sync before reading .py
python -m jupytext --sync notebook.ipynb
# Or fallback:
python -m jupytext --to py:percent notebook.ipynb -o notebook.py

Edit `.py` with percent-format

# %% [markdown]
# # Section Title

# %%
import pandas as pd

# %% tags=["parameters"]
param1 = "default"

Sync back (preserve outputs)

python -m jupytext --to ipynb --update notebook.py -o notebook.ipynb

nbformat (Micro-Edits & Batch)

Edit single cell

import nbformat

nb = nbformat.read("notebook.ipynb", as_version=4)
nb["cells"][3]["source"] = nb["cells"][3]["source"].replace("old", "new", 1)
nbformat.write(nb, "notebook.ipynb")

Add new cell

new_cell = nbformat.v4.new_code_cell(source="print('Hello')")
nb["cells"].insert(5, new_cell)

Delete cell

del nb["cells"][3]

papermill (Execute Notebooks)

# Basic
papermill input.ipynb output.ipynb

# With parameters
papermill input.ipynb output.ipynb -p data_path "/path" -p n_samples 1000

import papermill as pm
pm.execute_notebook("input.ipynb", "output.ipynb", parameters={"n_samples": 1000})

nbconvert (Format Conversion)

Format	Command
HTML	`jupyter nbconvert --to html notebook.ipynb`
PDF	`jupyter nbconvert --to pdf notebook.ipynb`
Script	`jupyter nbconvert --to script notebook.ipynb`
Markdown	`jupyter nbconvert --to markdown notebook.ipynb`

Execute and convert: jupyter nbconvert --execute --to html notebook.ipynb

Clear outputs: jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace notebook.ipynb

Common Issues

Issue	Solution
Outputs lost after sync	Use `--update` flag with Jupytext
Kernel not found	`jupyter kernelspec list` then specify `-k python3`
Large file size	Clear outputs before git commit
Windows venv	Use `.\.venv\Scripts\activate`

Jupytext (Structural Edits)

Setup & Sync

Edit .py with percent-format

Sync back (preserve outputs)

nbformat (Micro-Edits & Batch)

Edit single cell

Add new cell

Delete cell

papermill (Execute Notebooks)

nbconvert (Format Conversion)

Common Issues

Edit `.py` with percent-format

jupyter-notebooks

Jupyter Notebook Operations

Decision Tree

EditNotebook Tool (Cursor IDE)