enforce-notebook-run-order

Enforce the run order of Jupyter notebooks.

Jupyter notebooks are great for interactive data analysis. However, they can encourage a bad habit: running cells out of order. This can lead to notebooks being committed to the repository in a state where they don't run from top to bottom, and other collaborators may receive different results when trying to reproduce the analysis.

enforce-notebook-run-order attempts to fix this by raising an exception before each commit if any cells are run out of order.

Language Support

This tool works with all Jupyter notebook kernels, including:

• Python (IPython)
• R (IRkernel)
• Julia
• Scala, Java, C++, and many others

Any language kernel that produces standard .ipynb files with execution_count metadata is supported. The tool is language-agnostic and only inspects the notebook's execution order metadata.

Validation Requirements

For a notebook to be considered valid, it must meet the following requirements:

• All non-empty code cells must be executed: Each code cell with content must have an execution_count value (not None).
• Execution must start from 1: The first non-empty code cell must have execution_count=1.
• No gaps in execution sequence: Execution counts must be strictly sequential (1, 2, 3, ...) with no skipped numbers.

Examples:

• ✅ Valid: Cells with execution counts 1, 2, 3, 4
• ❌ Invalid: Cells starting with 0, 1, 2 (must start from 1)
• ❌ Invalid: Cells starting with 2, 3, 4 (must start from 1)
• ❌ Invalid: Cells with 1, 2, 4, 5 (gap at 3)
• ❌ Invalid: Cells with 1, 3, 2 (not sequential)
• ❌ Invalid: Cells with 1, 2, None (unexecuted cell)

Note: Empty code cells (cells with no content) are ignored and do not need to be executed.

Usage

enforce-notebook-run-order is designed to work primarily as a pre-commit hook, but can also be used as a standalone script when needed.

pre-commit hook (Recommended)

The intended way to use enforce-notebook-run-order is as a pre-commit hook to automatically validate notebook execution order before each commit.

To set it up, add the following to your .pre-commit-config.yaml:

repos:
-   repo: https://github.com/cmhac/enforce-notebook-run-order
    rev: <replace with latest version from https://github.com/cmhac/enforce-notebook-run-order/releases/>
    hooks:
    -   id: enforce-notebook-run-order

This will automatically check all notebooks in your repository before each commit, preventing out-of-order execution from being committed to your repository.

Standalone

For manual validation or CI integration, enforce-notebook-run-order can be used as a standalone script.

First, install it the same way you install other Python packages, such as:

pip install enforce-notebook-run-order

Run it with the path to the notebook(s) you want to check:

nbcheck my_notebook.ipynb my_other_notebook.ipynb

Or point it to a directory to check all notebooks in that directory:

nbcheck my_notebooks/

If no paths are specified, nbcheck will check all notebooks in the current directory.

You can also use the full enforce-notebook-run-order command, but the nbcheck command is provided as a convenience.