Jupyter Notebooks Best Practices
Numbered cells, clear outputs before commit, papermill for parameterized execution.
Jupyter Notebooks Best Practices is a free Learn AI with Python lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Learn AI with Python learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
The Notebook Double-Edged Sword
Jupyter notebooks are fantastic for exploration: run code in cells, see plots inline, iterate fast. But that same flexibility breeds messy, irreproducible work if you are not disciplined.
This lesson covers habits that keep notebooks clean and trustworthy.
Hidden State: The Core Problem
You can run cells in any order, and earlier results stick around in memory. This hidden state means a notebook can show correct outputs that no fresh run could reproduce.
Almost every notebook best practice exists to fight hidden state.
Run Cells Sequentially
Execution counts (the [1], [2] beside cells) should increase top to bottom. Out-of-order numbers like [7] above [3] are a red flag that the notebook depends on hidden state.
Write notebooks so they make sense read straight down.
Restart Kernel and Run All
The golden rule: before trusting or committing a notebook, do Kernel → Restart & Run All. This wipes memory and runs every cell from scratch.
If it runs clean top to bottom, the notebook is reproducible. If it breaks, you found hidden-state bugs.
Keep Cells Focused
One logical step per cell makes notebooks readable and re-runnable. Avoid giant cells doing ten things; avoid scattering one operation across many tiny cells.
Use Markdown cells to narrate sections like a report.
Move Reusable Code to Modules
When a function proves useful, move it out of the notebook into src/ and import it. This keeps notebooks thin, makes code testable, and avoids copy-paste drift across notebooks.
from src.features.build_features import make_features
X = make_features(df) # logic lives in a tested moduleThe Output Diff Problem
Notebooks store cell outputs (text, big tables, base64 images) inside the .ipynb JSON. Committing those makes Git diffs huge and noisy, and can leak data.
The fix: strip outputs before committing.
Clearing Outputs with nbstripout
nbstripout removes outputs from notebooks automatically. Install it as a Git filter so outputs are stripped on every commit without you remembering.
# pip install nbstripout
nbstripout --install # adds a git filter for this repo
# now committed notebooks have clean, output-free diffsParameterizing Notebooks with papermill
papermill runs a notebook programmatically with injected parameters, like calling a function. Tag a cell as parameters and papermill overrides those values per run.
# pip install papermill
# papermill analysis.ipynb out.ipynb -p dataset "may.csv" -p seed 42Parameterized Runs in Code
You can also drive papermill from Python to run the same analysis notebook over many inputs — a clean way to batch experiments.
import papermill as pm
for ds in ["jan.csv", "feb.csv", "mar.csv"]:
pm.execute_notebook(
"analysis.ipynb",
f"out_{ds}.ipynb",
parameters={"dataset": ds, "seed": 42},
)A Notebook Hygiene Checklist
Before sharing or committing a notebook:
- Restart kernel and Run All — it must pass clean
- Cells run top to bottom with increasing counts
- Reusable logic moved to
src/ - Outputs stripped (nbstripout)
- Markdown narrates the story
Quick Check: Trusting a Notebook
Before committing, you want to confirm the notebook is reproducible and free of hidden-state bugs.
Recap: Notebook Best Practices
You learned to keep notebooks clean and reproducible:
- Fight hidden state — run cells sequentially
- Restart & Run All before trusting or committing
- Move reusable code to
src/modules - nbstripout to clear outputs for clean Git diffs
- papermill for parameterized, batch notebook runs
That completes the AI Project Structure and Git Workflow course.
Frequently asked questions
Is the “Jupyter Notebooks Best Practices” lesson free?
Yes — the full text of “Jupyter Notebooks Best Practices” is free to read here on the web, and the Learn AI with Python course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Learn AI with Python course, upgrade to CoddyKit PRO.
What will I learn in “Jupyter Notebooks Best Practices”?
Numbered cells, clear outputs before commit, papermill for parameterized execution. You practise Learn AI with Python with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Learn AI with Python?
No prior experience is required. Learn AI with Python on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Jupyter Notebooks Best Practices” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Learn AI with Python lesson?
Yes. Every Learn AI with Python lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Professional AI Project Directory Structure
- Git for AI Projects
- Reproducibility: Seeds, Configs, and Environments
- Jupyter Notebooks Best Practices