Installation using pip

If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is to simply use :command:`pip`:

$ pip install ipython

That's it.

Installation from source

If you don't want to use :command:`pip`, 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 :command:`sudo`.

Windows

As mentioned above, on Windows, IPython requires :mod:`setuptools`, 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 setuptools.
2. Install pyreadline. You can use the command pip 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 --recursive 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 :mod:`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

IPython now uses git submodules to ship its javascript dependencies. If you run IPython from git master, you may need to update submodules once in a while with:

$ git submodule update

or

$ python setup.py submodule

Another option is to copy git hooks to your ./git/hooks/ directory to ensure that your submodules are up to date on each pull.

readline

As indicated above, on Windows, to get full functionality in the console version of IPython, PyReadline is needed. PyReadline is a separate, Windows only implementation of readline that uses native Windows calls through :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary installer available here.

On OSX, if you are using the built-in Python shipped by Apple, you will be missing a proper readline implementation as Apple ships instead a library called libedit that provides only some of readline's functionality. 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, IPython on OS X depends on the :mod:`gnureadline` module. We will not consider completion/history problems to be bugs for IPython if you are using libedit.

To get a working :mod:`readline` module on OS X, just do (with :mod:`pip` installed):

$ pip install gnureadline

When IPython is installed with :mod:`setuptools`, (e.g. using the pip command), the correct readline should be installed if you specify the terminal optional dependencies:

$ pip install "ipython[terminal]"

nose

To run the IPython test suite you will need the :mod:`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 :command:`pip`:

$ pip install nose

Another way of getting this is to do:

$ pip 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

pyzmq

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 pip install-able. If you are on Python 2.7, 3.3, or 3.4 on OSX or Windows, pyzmq has eggs and wheels that include ZeroMQ itself.

IPython.kernel.zmq depends on pyzmq >= 2.2.

pyzmq

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

Qt

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

pygments

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

pyzmq

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

Tornado

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.

Jinja

The IPython notebook uses the Jinja templating tool to render HTML pages.

MathJax

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, you can install MathJax locally.

A quick and easy method is to install it from a python session:

from IPython.external.mathjax import install_mathjax
install_mathjax()

If you need tighter configuration control, you can download your own copy of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link. When you have the file stored locally, install it with:

python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip

For unusual needs, IPython can tell you what directory it wants to find MathJax in:

python -m IPython.external.mathjax -d /some/other/mathjax

By default Mathjax will be installed in your ipython profile directory, but you can make system wide install, please refer to the documentation and helper function of :mod:`IPython.external.mathjax`

Browser Compatibility

The IPython notebook is officially supported on the following browsers:

• Chrome ≥ 13
• Safari ≥ 5
• Firefox ≥ 6

The is mainly due to the notebook's usage of WebSockets and the flexible box model.

The following browsers are unsupported:

• Safari < 5
• Firefox < 6
• Chrome < 13
• Opera (any): CSS issues, but execution might work
• Internet Explorer < 10

The following specific combinations are known NOT to work:

• Safari, IPython 0.12, tornado ≥ 2.2.0
• Safari with HTTPS connection to notebook and an untrusted certificate (websockets will fail)
• The diigo Chrome extension seems to interfere with scrolling

There are some early reports that the Notebook works on Internet Explorer 10, but we expect there will be some CSS issues related to the flexible box model.

pandoc

The most important dependency of nbconvert is Pandoc 1.10 or later, a document format translation program. This is not a Python package, so it cannot be expressed as a regular IPython dependency with setuptools.

To install pandoc on Linux, you can generally use your package manager:

sudo apt-get install pandoc

On other platforms, you can get pandoc from their website.