Introduction

Running a Jupyter notebook from the terminal is useful when you want notebook execution without opening the browser UI. The most common solution is jupyter nbconvert --execute, while tools such as papermill are better when the notebook needs parameters or repeatable automation.

The Standard Command: nbconvert --execute

For a normal notebook, the simplest command is:

jupyter nbconvert --to notebook --execute my_notebook.ipynb

This runs the notebook and writes an executed notebook file in the output location chosen by nbconvert. If you want to overwrite the original file with the executed outputs, add --inplace:

jupyter nbconvert --to notebook --execute --inplace my_notebook.ipynb

This is the usual choice for scheduled jobs, CI, and remote servers where you still want a real notebook file as the result.

Timeouts and Working Directory

Two options matter more than most people expect:

• timeout for long-running cells
• the working directory used during execution

A notebook that reads files with relative paths can fail if it is executed from the wrong directory. A notebook with heavy computation can fail if the default timeout is too short.

1jupyter nbconvert \
2  --to notebook \
3  --execute \
4  --inplace \
5  --ExecutePreprocessor.timeout=600 \
6  --ExecutePreprocessor.cwd=/path/to/project \
7  my_notebook.ipynb

If a cell may run for a very long time, you can disable the timeout entirely:

jupyter nbconvert --to notebook --execute --ExecutePreprocessor.timeout=-1 my_notebook.ipynb

Use papermill When the Notebook Needs Parameters

If the notebook should run with different input values each time, papermill is usually the better tool.

papermill input.ipynb output.ipynb -p learning_rate 0.01 -p epochs 50

Inside the notebook, create a parameters cell with defaults:

learning_rate = 0.001
epochs = 10

papermill replaces those values during execution and saves the result into a separate output notebook. This is a strong fit for data pipelines, reporting jobs, and experiments that need repeatable configuration.

Running Through Python Code

If you need notebook execution as part of a Python application rather than a shell script, use nbformat with ExecutePreprocessor.

1import nbformat
2from nbconvert.preprocessors import ExecutePreprocessor
3
4with open("my_notebook.ipynb") as f:
5    nb = nbformat.read(f, as_version=4)
6
7ep = ExecutePreprocessor(timeout=600, kernel_name="python3")
8ep.preprocess(nb, {"metadata": {"path": "."}})
9
10with open("my_notebook_executed.ipynb", "w") as f:
11    nbformat.write(nb, f)

This is useful when notebook execution is one step inside a larger Python-driven workflow.

Converting to a Script Instead

Sometimes the real goal is not to preserve the notebook format at all. In that case, convert the notebook to a script and run the script directly.

jupyter nbconvert --to script my_notebook.ipynb
python my_notebook.py

That can be a good debugging aid because the generated script is easier to inspect in stack traces and command-line logs. The tradeoff is that notebook-specific outputs and metadata are no longer the main execution artifact.

Common Pitfalls

• Forgetting that relative file paths depend on the execution working directory.
• Leaving the default timeout in place for notebooks with long-running cells.
• Running the command in the wrong virtual environment or conda environment.
• Expecting UI-specific behavior from a headless terminal run, especially for plotting backends.
• Using raw shell execution when the notebook really needs parameters and papermill would be clearer.

Summary

• Use jupyter nbconvert --to notebook --execute for the normal terminal-based notebook run.
• Add --inplace if you want to overwrite the original notebook with executed output.
• Set timeout and working directory explicitly for reliable automation.
• Use papermill when notebook parameters should change between runs.
• Use the Python API when notebook execution is part of a larger program.