papermill: run a Jupyter notebook from the command line

Run a notebook with papermill

papermill 2.7.0 (released February 27, 2026) requires Python 3.10 or newer. Install it with pip install papermill, then run papermill INPUT OUTPUT to execute every cell in INPUT and write a new notebook with all outputs to OUTPUT, leaving your original file clean.

pip install papermill
mkdir -p runs
papermill report.ipynb runs/report-2026-10-30.ipynb

papermill won't create a missing output folder, so mkdir -p runs comes first.

You can pick a specific Jupyter kernel with -k (or --kernel) and set the working directory the notebook runs in with --cwd, which helps when your cells load files using relative paths.

Pass parameters

To parameterize a notebook, put your default variable assignments in one cell and give that cell the parameters tag in Jupyter's cell metadata. papermill inserts a new cell tagged injected-parameters right after it with your overrides, so every cell below uses the new values.

# Cell tagged "parameters"
alpha = 0.1
n_batches = 5

papermill report.ipynb out.ipynb -p alpha 0.6 -p n_batches 3
papermill report.ipynb out.ipynb -f params.yaml

With -p alpha 0.6 -p n_batches 3, the injected cell contains # Parameters, alpha = 0.6 and n_batches = 3. You can pass values on the command line or load them from YAML:

• -p NAME VALUE turns integers, floats, True, False and None into Python values and keeps everything else a string.
• -r NAME VALUE keeps the value a raw string even if it looks like a number.
• -f PATH reads parameters from a YAML file, and -y TEXT takes a YAML string.

These are the main options and their defaults:

Watch the output while it runs

By default, papermill shows a progress bar of executed cells and keeps your cells' print statements out of the terminal. Pass --log-output to send the notebook's output to the logger as each cell runs; it also turns the cell bar off unless you add --progress-bar.

$ papermill report.ipynb out.ipynb -p alpha 0.6 -p n_batches 3 --log-output
Input Notebook:  report.ipynb
Output Notebook: out.ipynb
Executing notebook with kernel: python3
Executing Cell 1---------------------------------------
Ending Cell 1------------------------------------------
Executing Cell 2---------------------------------------
Ending Cell 2------------------------------------------
Executing Cell 3---------------------------------------
batches: 100%|██████████| 3/3 [00:00<00:00,  3.33it/s]
alpha is 0.6
Ending Cell 3------------------------------------------

Text-mode tqdm bars show up between the cell markers. To keep the notebook's streams apart from papermill's own log lines, pass --stdout-file and --stderr-file.

Because --request-save-on-cell-execute is on by default, papermill saves the output notebook after every cell, so you can open out.ipynb mid-run and look at the plots and tables of the cells that already finished.

Run it in the background

For a long notebook on a remote server, run papermill under nohup with the log redirected to a file and follow it with tail -F, or start it inside a tmux session that you can detach from and reattach to later.

nohup papermill report.ipynb out.ipynb --log-output > run.log 2>&1 &
tail -F run.log

When a cell raises an exception, papermill stops executing further cells, writes the traceback into the output notebook with an error banner at the top, prints a PapermillExecutionError, and exits with code 1. That exit code lets cron, systemd timers and CI pipelines detect the failure. papermill waits forever for a cell by default, so set --execution-timeout for unattended jobs.

nbconvert --execute as the alternative

If you don't need parameters, jupyter nbconvert already ships with Jupyter. jupyter nbconvert --to notebook --execute mynotebook.ipynb executes the cells and saves the result as mynotebook.nbconvert.ipynb.

jupyter nbconvert --to notebook --execute report.ipynb --output executed.ipynb
jupyter nbconvert --to notebook --execute report.ipynb --ExecutePreprocessor.timeout=600

Use --output to pick the filename or --inplace to overwrite the input notebook. The nbconvert docs still say each cell gets 30 seconds by default, but in a test with nbconvert 7.17.2 a 40-second cell finished without a timeout, so set --ExecutePreprocessor.timeout yourself when you want a limit. nbconvert stops at the first exception unless you pass --allow-errors.

Live progress from inside the notebook

papermill's bar tells you which cell is running, not how far along a multi-hour loop inside that cell is. With tqdm-live installed, from tqdm_live import tqdm inside the notebook streams your loop's bars to a live link, as long as the machine has outbound HTTPS. Widget bars from tqdm.notebook aren't patched, so import the text bar from tqdm_live.

tqdm_live.start_run("name") groups all bars under one link. When papermill finishes, the kernel exits and the run is marked finished. An exception in a cell doesn't mark the run failed on its own, so call tqdm_live.end_run("failed", exit_code=1) in an except block before re-raising. In an interactive notebook, where the kernel stays open, call tqdm_live.end_run("finished") in the last cell.