IPython

Overview

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.

Warning

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 distribute package and its easy_install command line program. In many scenarios, this provides the most simple method of installing IPython and its dependencies. More information about distribute can be found on its PyPI page.

Note

On Windows, IPython has a hard dependency on distribute. We hope to change this in the future, but for now on Windows, you must install distribute.

More general information about installing Python packages can be found in Python’s documentation.

Quickstart

If you have distribute 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,qtconsole,notebook,test]

This will get:

• pyzmq, needed for IPython’s parallel computing features, qt console and notebook.
• pygments, used by the Qt console for syntax highlighting.
• tornado, needed by the web-based notebook
• nose, used by the test suite.

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

$ iptest

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 distribute, (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 distribute installed, the easiest way of getting IPython is to simply 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.

Windows

As mentioned above, on Windows, IPython requires distribute, and it also requires the PyReadline library to properly support coloring and keyboard management (features that the default windows console doesn’t have). So on Windows, the installation procedure is:

1. Install distribute.
2. Install pyreadline. You can use the command easy_install pyreadline from a terminal, or the binary installer appropriate for your platform from the PyPI page.
3. Install IPython itself, which you can download from PyPI or from our site. Note that on Windows 7, you must right-click and ‘Run as administrator’ for the Start menu shortcuts to be created.

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.

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

Some users want to be able to follow the development branch as it changes. If you have distribute 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

from  http://ipython.org/ipython-doc/stable/install/install.html