This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Run IPython notebooks from the command line

Project Description

runipy: run IPython as a script

The IPython notebook provides an interactive interface to a Python interpreter.

  • Literate programming: the IPython notebook is an ideal format for writing “literate” programs, in which the code is part of a larger multi-media document. runipy lets you run such programs directly, without first converting to a pure Python script.
  • Report generation: runipy can run the notebook and convert it into HTML in one go, making it an easy way to automate reports.
  • Data pipeline: if you use IPython notebooks to create a data pipeline, runipy lets you automate that pipeline without losing the notebook formatting.


runipy currently supports IPython versions 2.4.x, 3.2.x and the current development version of 4.x.


The easiest way to install runipy is with pip:

$ pip install runipy

Command-line use

To run a .ipynb file as a script, run:

$ runipy MyNotebook.ipynb

To save the output of each cell back to the notebook file, run:

$ runipy -o MyNotebook.ipynb

To save the notebook output as a new notebook, run:

$ runipy MyNotebook.ipynb OutputNotebook.ipynb

To run a .ipynb file and generate an HTML report, run:

$ runipy MyNotebook.ipynb --html report.html

Passing Arguments

You can pass arguments to the notebook through environment variables. The use of environment variables is OS- and shell- dependent, but in a typical UNIX-like environment they can be passed on the command line before the program name:

$ myvar=value runipy MyNotebook.ipynb

Here is one way this can be done from pure python:

from os import environ
from subprocess import call

environ['myvar'] = 'value'
call(["runipy", "MyNotebook.ipynb"])

Then in the notebook, to access myvar:

from os import environ
myvar = environ['myvar']

environ is just a dict, so you can use .get() to fall back on a default value:

from os import environ
myvar = environ.get('myvar', 'default!')

Stdin / Stdout

runipy can read stdin and stdout and sit in a UNIX pipeline:

$ runipy --stdout < MyNotebook.ipynb > OutputNotebook.ipynb

$ cat MyNotebook.ipynb | runipy --stdout > OutputNotebook.ipynb

Programmatic use

It is also possible to run IPython notebooks from Python, using:

from runipy.notebook_runner import NotebookRunner
from IPython.nbformat.current import read

notebook = read(open("MyNotebook.ipynb"), 'json')
r = NotebookRunner(notebook)

and you can enable pylab with:

r = NotebookRunner(notebook, pylab=True)

The notebook is stored in the object and can be saved using:

from IPython.nbformat.current import write
write(r.nb, open("MyOtherNotebook.ipynb", 'w'), 'json')

run_notebook() takes two optional arguments. The first, skip_exceptions, takes a boolean value (False by default). If True, exceptions will be ignored and the notebook will continue to execute cells after encountering an exception. The second argument is progress_callback, which must be either None or a function that takes one argument. This function is called after execution of each cell with the 0-based index of the cell just evaluated. This can be useful for tracking progress of long-running notebooks.


Portions of the code are based on code by Min RK

Thanks to Kyle Kelley, Nitin Madnani, George Titsworth, Thomas Robitaille, Andrey Tatarinov, Matthew Brett, Adam Haney, Nathan Goldbaum, Adam Ginsburg, Gustavo Bragança, Tobias Brandt, Andrea Zonca, Aaron O’Leary, Simon Guillot, Fernando Correia, Takashi Nishibayashi, Simon Conseil, and Thomas French for patches, documentation fixes, and suggestions.

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
runipy-0.1.5.tar.gz (24.5 kB) Copy SHA256 Checksum SHA256 Source Oct 19, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting