People love to hate Jupyter Notebooks!

They're missing out on a great communication tool.

Here's how data scientists and machine learners can

build great Jupyter Notebooks that people love to read

🧮 Fix your dang code

You can make a mess in notebooks when experimenting.

  1. All Imports into Cell 1
  2. Extract some functions and classes
  4. Fix your variable names
  5. Fix the order and outputs
  6. Use black to standardize your code format

✒️ Jupyter has Markdown Cells!

Use them.

If you're not using Markdown in your Notebooks, you should not be using Notebooks.

Write some prose to explain your code.

Whether analysis or model, do yourself a favour and document it.

In case you need a markdown guide.

🔂 Final checks

We all do it.

We forget to run a cell and wonder for an embarrassing amount of time, why we have an error in the next one.

Before you share your notebook:

  1. Restart Kernel to forget all variables
  2. Run All Cells

Not by hand. Automatic.

It'll show any mix ups

🏆 Extra Credit

🦾 Use nbconvert to run all cells from the command line

🧠 Write a utils file with reusable functions

⌨ Learn keyboard shortcuts for efficiency

🎨 Make it interactive with ipykernel


  • Care about code quality
  • Use markdown cells (More than just headings)
  • Make sure the notebook runs
  • Use extra tools to make your life easier