How to run an .ipynb Jupyter Notebook from terminal?

Question

I have some code in a .ipynb file and got it to the point where I don't really need the "interactive" feature of IPython Notebook. I would like to just run it straight from a Mac Terminal Command Line.

Basically, if this were just a .py file, I believe I could just do python filename.py from the command line. Is there something similar for a .ipynb file?

if you go to the runipy page referenced above you see that it is unmaintained and they point to Jupyter's "execute api" at https://nbconvert.readthedocs.io/en/latest/execute_api.html — markgalassi, May 28 '22 at 16:32

score 234 · Answer 1 · answered Feb 23 '16 at 08:50

234

nbconvert allows you to run notebooks with the --execute flag:

jupyter nbconvert --execute <notebook>

If you want to run a notebook and produce a new notebook, you can add --to notebook:

jupyter nbconvert --execute --to notebook <notebook>

Or if you want to replace the existing notebook with the new output:

jupyter nbconvert --execute --to notebook --inplace <notebook>

Since that's a really long command, you can use an alias:

alias nbx="jupyter nbconvert --execute --to notebook"
nbx [--inplace] <notebook>

answered Feb 23 '16 at 08:50

minrk

37,545
9
92
87

13

This turns the notebook into a static HTML page – Jim Daniël Teunis Sep 29 '18 at 15:25
5

Documentation or this and programmatic ways of running notebooks can be found at https://nbconvert.readthedocs.io/en/latest/execute_api.html#module-nbconvert.preprocessors – TomDotTom Mar 05 '19 at 19:27
Is there a way to specify which cells to execute? For example cell 10 and all below, or a range cell 10 to cell 20. – Al Conrad Jul 25 '19 at 16:19
3

Also, if you have long running cells, [you can set](https://nbconvert.readthedocs.io/en/latest/execute_api.html) `--ExecutePreprocessor.timeout=[timeout_in_seconds]` (use `-1` for no restriction). – Zaccharie Ramzi Aug 07 '19 at 08:07
The latest updates makes it work like this, you get a HTML out the notebook file `jupyter-nbconvert --execute 03-Print\ Formatting\ with\ Strings.ipynb` – b-ak Sep 16 '19 at 13:44
For me the first command produces an error `Please specify an output format with '--to '.`. It works with `jupyter nbconvert --to python --execute `. – sneawo Mar 03 '23 at 09:30
1

I had to do the following steps to get nbconvert to run `pip install ipykernel ` and `python -m ipykernel install --user --name=python3` – user15420598 Apr 11 '23 at 19:20

score 163 · Accepted Answer · edited Nov 22 '19 at 07:01

163

From the command line you can convert a notebook to python with this command:

jupyter nbconvert --to python nb.ipynb

https://github.com/jupyter/nbconvert

You may have to install the python mistune package:

sudo pip install -U mistune

edited Nov 22 '19 at 07:01

evandrix

6,041
4
27
38

answered Feb 22 '16 at 03:48

ditkin

6,774
1
35
37

15

Subcommand `ipython nbconvert` is deprecated in favor of jupyter nbconvert – PenguinEngineer Nov 06 '17 at 17:33
20

I don't think this answer is correct. II realise it works but the question is how to run .ipynb from terminal, not how to convert it into a .py and then run it. – Giacomo Nov 23 '18 at 12:48
3

Nbconvert will fail if any cell takes longer than 30s to run, you may want to add `--ExecutePreprocessor.timeout=600`. – bckygldstn Jan 24 '19 at 17:15
1

The latest updates makes it work like this, you get a HTML out the notebook file `jupyter-nbconvert --execute 03-Print\ Formatting\ with\ Strings.ipynb` – b-ak Sep 16 '19 at 13:45

score 61 · Answer 3 · answered Nov 08 '19 at 21:39

61

In your Terminal run ipython:

ipython

then locate your script and put there:

%run your_script.ipynb

answered Nov 08 '19 at 21:39

Martin Ptacek

619
5
3

how could this be put into a shell script – baxx Feb 25 '20 at 17:49
33

@baxx `ipython -c "%run your_script.ipynb"` – Keto Oct 04 '20 at 10:59
can you do a Makefile with this? – Carlos Mougan Apr 07 '21 at 21:00
@CarlosMougan see also [this answer](https://stackoverflow.com/a/68720825/2641825) using [nbconvert](https://nbconvert.readthedocs.io/en/latest/execute_api.html#example) to run notebooks from python. – Paul Rougieux Mar 09 '22 at 17:06

score 44 · Answer 4 · answered Feb 22 '16 at 03:43

44

You can export all your code from .ipynb and save it as a .py script. Then you can run the script in your terminal.

Hope it helps.

answered Feb 22 '16 at 03:43

Eric

2,636
21
25

27

doesn't answer the original question – baxx Feb 25 '20 at 17:47

score 26 · Answer 5 · answered Mar 09 '21 at 09:54

26

Using ipython:

ipython --TerminalIPythonApp.file_to_run=<notebook>.ipynb

Normally, I would prefer this option as it is really self-describing. If you prefer to use less characters, use:

ipython -c "%run <notebook>.ipynb"

which is basically what Keto already suggested (unfortunately a little bit hidden) as a comment.

answered Mar 09 '21 at 09:54

Murmel

5,402
47
53

3

Guys, admit it, you would not find the comment without this answer, so why not upvote both?:) – mirekphd Jun 09 '21 at 19:04
I'd also like to add that it is prudent to specify an absolute path to the notebook (it can save you a lot of searching if `ipython` is not the only part of the "run chain" (in my case `ipython` was inside a bash script run from a Kubernetes CronJob and it would fail without the full absolute path to the notebook). – mirekphd Jun 10 '21 at 14:41

score 12 · Answer 6 · answered Oct 18 '19 at 00:12

In my case, the command that best suited me was:

jupyter nbconvert --execute --clear-output <notebook>.ipynb

Why? This command does not create extra files (just like a .py file) and the output of the cells is overwritten everytime the notebook is executed.

If you run:

jupyter nbconvert --help

--clear-output Clear output of current file and save in place, overwriting the existing notebook.

score 10 · Answer 7 · answered Apr 05 '18 at 06:19

10

For new version instead of:

ipython nbconvert --to python <YourNotebook>.ipynb

You can use jupyter instend of ipython:

jupyter nbconvert --to python <YourNotebook>.ipynb

answered Apr 05 '18 at 06:19

Vijay Panchal

317
3
8

1

how is this an answer to the question? – baxx Feb 25 '20 at 17:47

score 5 · Answer 8 · edited Sep 02 '18 at 18:30

5

Update with quoted comment by author for better visibility:

Author's note "This project started before Jupyter's execute API, which is now the recommended way to run notebooks from the command-line. Consider runipy deprecated and unmaintained." – Sebastian Palma

Install runipy library that allows running your code on terminal

pip install runipy

After just compiler your code:

runipy <YourNotebookName>.ipynb

You can try cronjob as well. All information is here

edited Sep 02 '18 at 18:30

Oliver Bestwalter

5,219
33
47

answered Feb 10 '18 at 12:05

Axis

2,066
2
21
40

13

Author's note "This project started before Jupyter's execute API, which is now the recommended way to run notebooks from the command-line. Consider runipy deprecated and unmaintained." – Sebastián Palma Mar 23 '18 at 15:15

score 5 · Answer 9 · answered Jul 16 '20 at 11:30

5

I had the same problem and I found papermill. The advantages against the others solutions is that you can see the results while the notebook is running. I find this feature interesting when the notebook takes very long. It is very easy to use:

pip install papermill
papermill notebook.ipynb output.ipynb

It has also, other handy options as saving the output file to Amazon S3, Google Cloud, etc. See the page for more information.

answered Jul 16 '20 at 11:30

pglez82

489
5
11

papermill also 1) displays a progress bar of your notebooks execution, 2) save the notebook executed without touching the original notebook, 3) In case of execution failure, the executed notebook will show you exactly where (the cell number is provided and the cell is highlighted in red) you code failed. It also has many configuration feature. papermill is likely better than `nbconvert` and quite easy to use. – Adrien Pacifico Sep 01 '22 at 11:38

score 3 · Answer 10 · answered Oct 26 '22 at 15:25

I've made some research on this topic and wrote an article on 4 ways to run Jupyter Notebook in command line below is summary of my findings.

1. Use `nbconvert`

The nbconvert package is already installed in Jupyter Notebook. It can be used to execute notebook. Additionally it has many features:

can export notebook to PDF or HTML,
can hide code in output notebook,
can execute notebook even with errors in cells.

Example notebook execution:

jupyter nbconvert --execute --to notebook --allow-errors your-notebook.ipynb

The above command will output your-notebook.nbconvert.ipynb file and will execute all cells even with errors.

2. Use `papermill`

The papermill allows you to parametrize notebook. You can define variables as parameters (with cell tags).

Example command:

papermill -p name Piotrek your-notebook.ipynb output-notebook.ipynb

Example notebook with injected parameters:

3. Manually download notebook as `.py` script

There is an option to manually download notebook as .py script:

After download you can add execution rights to the file and run it as a command line script.

4. Use `jupytext`

The jupytext package allows you to synchronize .ipynb file with .py file. You don't need to manually convert notebook to script.

Unfortunately, pairing .ipynb with .py in jupytext does not seem to work. Would be great if it did. — James Hirschorn, Apr 01 '23 at 15:38

score 3 · Answer 11 · answered Dec 22 '22 at 18:35

3

There is now a jupyter run subcommand that will execute a notebook.

jupyter run notebook.ipynb

More on this command can be found in the Jupyter documentation.

answered Dec 22 '22 at 18:35

Geoffrey Hing

1,575
2
15
22

score 2 · Answer 12 · answered May 24 '20 at 15:39

You can also use the boar package to run your notebook within a python code.

from boar.running import run_notebook

outputs = run_notebook("nb.ipynb")

If you update your notebook, you won't have to convert it again to a python file.

More information at:

https://github.com/alexandreCameron/boar/blob/master/USAGE.md

score 1 · Answer 13 · answered Jul 07 '20 at 06:28

From the terminal run

jupyter nbconvert --execute --to notebook --inplace --allow-errors --ExecutePreprocessor.timeout=-1 my_nb.ipynb

The default timeout is 30 seconds. -1 removes the restriction.

If you wish to save the output notebook to a new notebook you can use the flag --output my_new_nb.ipynb

score 0 · Answer 14 · answered Apr 19 '22 at 07:14

You can also use jupytext https://jupytext.readthedocs.io/en/latest/index.html.

This allows you to pair your notebook. So for each ipynb file you have a .py file as well with some comments. The .py file can be executed as usual. You can enjoy benefits of two worlds with the cost of one extra file though.

Oh, and by the way if you are using version control you can only commit .py files with a nice diff instead of the ugly .ipynb diffs.

(The syntax in the .py files is similar to Databricks notebooks iy you are familiar with them...)

score -1 · Answer 15 · answered Sep 24 '22 at 08:34

-1

In a batch file paste the below. Use ipython to run .ipynb files.

@echo on
call "C:\ProgramData\Anaconda3\Scripts\activate.bat"
ipython "path\test.ipynb"
pause

answered Sep 24 '22 at 08:34

pRo

89
12

How to run an .ipynb Jupyter Notebook from terminal?

15 Answers15

1. Use `nbconvert`

2. Use `papermill`

3. Manually download notebook as `.py` script

4. Use `jupytext`

Linked

Related

How to run an .ipynb Jupyter Notebook from terminal?

15 Answers15

1. Use nbconvert

2. Use papermill

3. Manually download notebook as .py script

4. Use jupytext

Linked

Related

1. Use `nbconvert`

2. Use `papermill`

3. Manually download notebook as `.py` script

4. Use `jupytext`