juplit
Literate programming for Python — write in notebooks, commit clean Python, keep AI agents fast.
Why juplit
Jupyter notebooks are great for development: you can write prose next to code, run cells incrementally, and explore interactively. But .ipynb files are JSON blobs that create real problems:
- Git history is cluttered — every output change, cell execution count, or metadata tweak shows up as a diff
- AI agents struggle — JSON notebooks are token-heavy and hard to reason over compared to plain Python
- Code review is painful — notebooks don't diff cleanly in pull requests
juplit gives you the best of both worlds. You write in jupytext percent-format .py files — plain Python that AI agents can read and reason over efficiently. You generate .ipynb files locally for interactive Jupyter sessions, but keep them out of git. The .py file is always the source of truth.
Installation
CLI usage
juplit nb # generate .ipynb from .py files (run after cloning)
juplit sync # sync .py <-> .ipynb after editing
juplit clean # sync then delete all .ipynb files (before AI agent sessions)
juplit skill # print the Claude Code skill file for juplit
Artifact notebooks
Some notebooks exist for their outputs — an analysis run against a live endpoint, where
the plots and tables are the deliverable and nobody will re-run it to review it. Declare
those pairs and juplit stops treating the .ipynb as disposable:
For a declared pair, nb and sync keep the outputs, and clean keeps the file
(--force deletes it anyway). Every cell juplit executes records which version of its
source produced its outputs, so a cell whose code has moved on is reported and blocked
rather than passing silently:
juplit check # pre-commit / CI: reads committed files only, no kernel needed
juplit run nb.py --stale # re-execute just the cells that drifted
Committed does not mean untouched: execution counts, per-run timestamps and progress-bar spam are stripped on every write, so re-running with the same results produces no diff.
The execution loop
juplit can hold a Jupyter kernel alive between CLI calls, with no Jupyter server — so an agent (or you) can try a cell, look at the result, and commit only the version that worked:
juplit cells experiments/ablation.py # index: one line per cell, digests, no base64
juplit view experiments/ablation.py 3-7 # just those cells, with their outputs
juplit kernel start
juplit try 'df.groupby("arm").score.mean()' # prints; writes nothing
juplit add-cell experiments/ablation.py --from-last # the snippet + the outputs you saw
juplit html experiments/ablation.py # standalone page for a non-Python reader
try never writes. run always writes. That is the whole safety rule.
See the artifact notebooks tutorial for the full walkthrough.
Project setup (pyproject.toml)
For a new project, use the cookiecutter template
[project]
dependencies = ["juplit>=0.1.0"]
[dependency-groups]
dev = ["poethepoet>=0.25.0", "pytest>=8.0.0", "ipykernel>=6.0.0", "pre-commit>=3.0.0"]
[tool.poe.tasks]
init = {cmd = "pre-commit install"}
sync = {cmd = "juplit sync"}
nb = {cmd = "juplit nb"}
clean = {cmd = "juplit clean"}
test = {cmd = "pytest"}
[tool.juplit]
notebook_src_dir = "your_module" # directory juplit scans for paired .py files
[tool.jupytext]
formats = "ipynb,py:percent"
[tool.pytest.ini_options]
python_files = ["*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
juplit finds the nearest pyproject.toml by walking up from the current directory, so the CLI works from any subdirectory.
Separating logic from tests with test()
Use test() to gate inline test code so it runs interactively in Jupyter and under pytest, but never on import:
from juplit import test
# %%
def add(a: int, b: int) -> int:
return a + b
# %%
if test():
assert add(1, 2) == 3
assert add(-1, 1) == 0
print("add() tests pass")
pytest picks up these blocks automatically when you configure:
No def test_* functions required — just if test(): blocks next to the code they test.
Under pytest, test() is True only for modules inside the run's own
[tool.juplit] notebook_src_dirs (read from the pyproject at pytest's rootdir, by a
pytest plugin juplit installs). A package you install that is itself written with
if test(): blocks therefore does not run them in your test suite. (Since 0.3.0:
earlier versions ran every imported module's blocks under any pytest run.)
You can also mix standard pytest functions with if test(): scaffolding blocks. Because if test(): runs at module scope during pytest collection, variables it sets up are available to def test_* functions:
from juplit import test
# %%
def compute(x: int) -> int:
return x * 2 + 1
# %%
if test():
inputs = [1, 3, -1]
expected = [3, 7, -1]
def test_compute():
for x, e in zip(inputs, expected):
assert compute(x) == e
Paired notebook format
A .py file is recognized as a paired notebook when its header contains:
Cells are delimited with # %% (code) and # %% [markdown] (prose).
Claude Code integration
Generate a skill file for Claude Code so it understands the juplit workflow:
For a skill on how to migrate nbdev repos to juplit: