IPython Documentation

Table Of Contents

Previous topic


Next topic

Using IPython for interactive work

This Page


This document describes the steps required to install IPython. IPython is organized into a number of subpackages, each of which has its own dependencies. All of the subpackages come with IPython, so you don’t need to download and install them separately. However, to use a given subpackage, you will need to install all of its dependencies.

Please let us know if you have problems installing IPython or any of its dependencies. Officially, IPython requires Python 2.6, 2.7, 3.1, or 3.2.


Since version 0.11, IPython has a hard syntax dependency on 2.6, and will no longer work on Python <= 2.5. You can find older versions of IPython which supported Python <= 2.5 here

Some of the installation approaches use the setuptools package and its easy_install command line program. In many scenarios, this provides the most simple method of installing IPython and its dependencies. It is not required though. More information about setuptools can be found on its website.


On Windows, IPython does depend on setuptools, and it is recommended that you install the distribute package, which improves setuptools and fixes various bugs. Installing on Python 3 requires distribute on all platforms.

We hope to remove this dependency in the future.

More general information about installing Python packages can be found in Python’s documentation at http://www.python.org/doc/.


If you have setuptools installed and you are on OS X or Linux (not Windows), the following will download and install IPython and the main optional dependencies:

$ easy_install ipython[zmq,test]

This will get pyzmq, which is needed for IPython’s parallel computing features as well as the nose package, which will enable you to run IPython’s test suite.

To run IPython’s test suite, use the iptest command:

$ iptest

Read on for more specific details and instructions for Windows.

Installing IPython itself

Given a properly built Python, the basic interactive IPython shell will work with no external dependencies. However, some Python distributions (particularly on Windows and OS X), don’t come with a working readline module. The IPython shell will work without readline, but will lack many features that users depend on, such as tab completion and command line editing. If you install IPython with setuptools, (e.g. with easy_install), then the appropriate readline for your platform will be installed. See below for details of how to make sure you have a working readline.

Installation using easy_install

If you have setuptools installed, the easiest way of getting IPython is to simple use easy_install:

$ easy_install ipython

That’s it.

Installation from source

If you don’t want to use easy_install, or don’t have it installed, just grab the latest stable build of IPython from here. Then do the following:

$ tar -xzf ipython.tar.gz
$ cd ipython
$ python setup.py install

If you are installing to a location (like /usr/local) that requires higher permissions, you may need to run the last command with sudo.



On Windows, IPython requires setuptools or distribute.

We hope to remove this dependency in the future.

There are a few caveats for Windows users. The main issue is that a basic python setup.py install approach won’t create .bat file or Start Menu shortcuts, which most users want. To get an installation with these, you can use any of the following alternatives:

  1. Install using easy_install.
  2. Install using our binary .exe Windows installer, which can be found here
  3. Install from source, but using setuptools (python setupegg.py install).

IPython by default runs in a terminal window, but the normal terminal application supplied by Microsoft Windows is very primitive. You may want to download the excellent and free Console application instead, which is a far superior tool. You can even configure Console to give you by default an IPython tab, which is very convenient to create new IPython sessions directly from the working terminal.

Note for Windows 64 bit users: you may have difficulties with the stock installer on 64 bit systems; in this case (since we currently do not have 64 bit builds of the Windows installer) your best bet is to install from source with the setuptools method indicated in #3 above. See this bug report for further details.

Installing the development version

It is also possible to install the development version of IPython from our Git source code repository. To do this you will need to have Git installed on your system. Then just do:

$ git clone https://github.com/ipython/ipython.git
$ cd ipython
$ python setup.py install

Again, this last step on Windows won’t create .bat files or Start Menu shortcuts, so you will have to use one of the other approaches listed above.

Some users want to be able to follow the development branch as it changes. If you have setuptools installed, this is easy. Simply replace the last step by:

$ python setupegg.py develop

This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your IPython at any time, just do:

$ git pull

Basic optional dependencies

There are a number of basic optional dependencies that most users will want to get. These are:

  • readline (for command line editing, tab completion, etc.)
  • nose (to run the IPython test suite)
  • pexpect (to use things like irunner)

If you are comfortable installing these things yourself, have at it, otherwise read on for more details.


In principle, all Python distributions should come with a working readline module. But, reality is not quite that simple. There are two common situations where you won’t have a working readline module:

  • If you are using the built-in Python on Mac OS X.
  • If you are running Windows, which doesn’t have a readline module.

When IPython is installed with setuptools, (e.g. with easy_install), readline is added as a dependency on OS X, and PyReadline on Windows, and will be installed on your system. However, if you do not use setuptools, you may have to install one of these packages yourself.

On OS X, the built-in Python doesn’t not have readline because of license issues. Starting with OS X 10.5 (Leopard), Apple’s built-in Python has a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit seem to have been resolved. While you may find libedit sufficient, we have occasional reports of bugs with it and several developers who use OS X as their main environment consider libedit unacceptable for productive, regular use with IPython.

Therefore, we strongly recommend that on OS X you get the full readline module. We will not consider completion/history problems to be bugs for IPython if you are using libedit.

To get a working readline module, just do (with setuptools installed):

$ easy_install readline


Other Python distributions on OS X (such as fink, MacPorts and the official python.org binaries) already have readline installed so you likely don’t have to do this step.

If needed, the readline egg can be build and installed from source (see the wiki page at http://web.archive.org/web/20090614162410/ipython.scipy.org/moin/InstallationOSXLeopard).

On Windows, you will need the PyReadline module. PyReadline is a separate, Windows only implementation of readline that uses native Windows calls through ctypes. The easiest way of installing PyReadline is you use the binary installer available here.


To run the IPython test suite you will need the nose package. Nose provides a great way of sniffing out and running all of the IPython tests. The simplest way of getting nose, is to use easy_install:

$ easy_install nose

Another way of getting this is to do:

$ easy_install ipython[test]

For more installation options, see the nose website.

Once you have nose installed, you can run IPython’s test suite using the iptest command:

$ iptest


The pexpect package is used in IPython’s irunner script, as well as for managing subprocesses. IPython now includes a version of pexpect in IPython.external, but if you have installed pexpect, IPython will use that instead. On Unix platforms (including OS X), just do:

$ easy_install pexpect

Windows users are out of luck as pexpect does not run there.

Dependencies for IPython.parallel (parallel computing)

IPython.kernel has been replaced by IPython.parallel, which uses ZeroMQ for all communication.

IPython.parallel provides a nice architecture for parallel computing. The main focus of this architecture is on interactive parallel computing. These features require just one package: PyZMQ. See the next section for PyZMQ details.

On a Unix style platform (including OS X), if you want to use setuptools, you can just do:

$ easy_install ipython[zmq]    # will include pyzmq

Security in IPython.parallel is provided by SSH tunnels. By default, Linux and OSX clients will use the shell ssh command, but on Windows, we also support tunneling with paramiko.

Dependencies for IPython.zmq


IPython 0.11 introduced some new functionality, including a two-process execution model using ZeroMQ for communication. The Python bindings to ZeroMQ are found in the PyZMQ project, which is easy_install-able once you have ZeroMQ installed. If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows, pyzmq has eggs that include ZeroMQ itself.

IPython.zmq depends on pyzmq >= 2.1.4.

Dependencies for the IPython QT console


Like the IPython.parallel package, the QT Console requires ZeroMQ and PyZMQ.


Also with 0.11, a new GUI was added using the work in IPython.zmq, which can be launched with ipython qtconsole. The GUI is built on Qt, and works with either PyQt, which can be installed from the PyQt website, or PySide, from Nokia.


The syntax-highlighting in ipython qtconsole is done with the pygments project, which is easy_install-able.

Dependencies for the IPython HTML notebook

The IPython notebook is a notebook-style web interface to IPython and can be started withe command ipython notebook.


Like the IPython.parallel and IPython.frontend.qt.console packages, the HTML notebook requires ZeroMQ and PyZMQ.


The IPython notebook uses the Tornado project for its HTTP server. Tornado 2.1 is required, in order to support current versions of browsers, due to an update to the websocket protocol.


The IPython notebook uses the MathJax Javascript library for rendering LaTeX in web browsers. Because MathJax is large, we don’t include it with IPython. Normally IPython will load MathJax from a CDN, but if you have a slow network connection, or want to use LaTeX without an internet connection at all, we do include a utility to aid in downloading MathJax and installing it into the proper location:

from IPython.external.mathjax import install_mathjax

This function does require write access to the IPython install directory, so if you have a system-wide Python install, it may need to be done from a sudo python session.

Browser Compatibility

The notebook uses WebSockets and the flexible box model. These features are available in the following browsers:

  • Chrome
  • Safari
  • Firefox 6 and above
  • Firefox 4 and 5: These browsers have WebSocket support, but it is disabled by default. If you’re unable to upgrade, you can enable it by entering about:config in the URL bar and then setting network.websocket.enabled and network.websocket.override-security-block to true.

Internet Explorer 9 does not support WebSockets or the flexible box model, but these features should appear in Internet Explorer 10.