diff --git a/docs/source/install/install.rst b/docs/source/install/install.rst
index 5b21e5b..77416dd 100644
--- a/docs/source/install/install.rst
+++ b/docs/source/install/install.rst
@@ -2,29 +2,27 @@ IPython requires Python 2.7 or ≥ 3.3.
.. note::
- If you need to use Python 2.6 or 3.2, you can find IPython 1.0
- `here `__.
+ If you need to use Python 2.6 or 3.2, you can find IPython 1.x
+ `here `__,
+ or get it with pip::
+
+ pip install 'ipython<2'
+
Quickstart
==========
-If you have :mod:`setuptools`,
+If you have :mod:`pip`,
the quickest way to get up and running with IPython is:
.. code-block:: bash
$ pip install "ipython[all]"
-This will download and install IPython and its main optional dependencies:
-
-- jinja2, needed for the notebook
-- sphinx, needed for nbconvert
-- pyzmq, needed for IPython's parallel computing features, qt console and
- notebook
-- pygments, used by nbconvert and the Qt console for syntax highlighting
-- tornado, needed by the web-based notebook
-- nose, used by the test suite
-- readline (on OS X) or pyreadline (on Windows), needed for the terminal
+This will download and install IPython and its main optional dependencies for the notebook,
+qtconsole, tests, and other functionality.
+Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable,
+and will not be pulled in by pip.
To run IPython's test suite, use the :command:`iptest` command:
@@ -53,11 +51,6 @@ In many scenarios, this is the simplest method of installing Python packages.
More information about :mod:`pip` can be found on
`its PyPI page `__.
-.. note::
-
- On Windows, IPython *requires* :mod:`setuptools`. We hope to
- change this in the future, but for now on Windows, you *must* install
- :mod:`setuptools` to use IPython.
More general information about installing Python packages can be found in
`Python's documentation `_.
@@ -71,15 +64,14 @@ with no external dependencies. However, some Python distributions
(particularly on Windows and OS X), don't come with a working :mod:`readline`
module. The IPython shell will work without :mod:`readline`, but will lack
many features that users depend on, such as tab completion and command line
-editing. If you install IPython with :mod:`setuptools`, (e.g. with
-`pip`), then the appropriate :mod:`readline` for your platform will be
-installed. See below for details of how to make sure you have a working
-:mod:`readline`.
+editing. If you install IPython with :mod:`pip`,
+then the appropriate :mod:`readline` for your platform will be installed.
+See below for details of how to make sure you have a working :mod:`readline`.
Installation using pip
----------------------
-If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is
+If you have :mod:`pip`, the easiest way of getting IPython is
to simply use :command:`pip`:
.. code-block:: bash
@@ -93,7 +85,7 @@ 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
+grab the latest stable build of IPython from `here
`_. Then do the following:
.. code-block:: bash
@@ -108,39 +100,20 @@ 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
+As mentioned above, terminal IPython 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.
+1. Install `pip `_, if you don't have it already.
+2. Install IPython: ``pip install ipython``.
-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.
-.. _Console: http://sourceforge.net/projects/console
-
-
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:
+need to have Git installed on your system. Then do:
.. code-block:: bash
@@ -149,18 +122,16 @@ need to have Git installed on your system. Then just do:
$ 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:
+you have :mod:`pip`, you can replace the last step by:
.. code-block:: bash
- $ python setupegg.py develop
+ $ pip install -e .
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:
+Then, if you want to update your IPython at any time, do:
.. code-block:: bash
@@ -191,6 +162,7 @@ get. These are:
* readline (for command line editing, tab completion, etc.)
* nose (to run the IPython test suite)
+* mock (Python < 3, also for tests)
If you are comfortable installing these things yourself, have at it, otherwise
read on for more details.
@@ -209,7 +181,7 @@ 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
+On OS X, 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
@@ -219,7 +191,7 @@ 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`
+To get a working :mod:`readline` module on OS X, do (with :mod:`pip`
installed):
.. code-block:: bash
@@ -231,7 +203,7 @@ installed):
Other Python distributions on OS X (such as Anaconda, fink, MacPorts)
already have proper readline so you likely don't have to do this step.
-When IPython is installed with :mod:`setuptools`, (e.g. using the
+When IPython is installed with :mod:`pip`, (e.g. using the
``pip`` command), the correct readline should be installed if you specify the `terminal`
optional dependencies:
@@ -270,84 +242,67 @@ iptest command:
Dependencies for IPython.parallel (parallel computing)
======================================================
-IPython.parallel provides a nice architecture for parallel computing, with a
-focus on fluid interactive workflows. These features require just one package:
-PyZMQ. See the next section for PyZMQ details.
+IPython's inter-process communication uses the PyZMQ_ bindings for the ZeroMQ_ messaging library.
+This is the only dependency for :mod:`IPython.parallel`.
-On a Unix style platform (including OS X), if you want to use
-:mod:`setuptools`, you can just do:
+Shortcut:
.. code-block:: bash
- $ pip install "ipython[zmq]" # will include pyzmq
+ pip install "ipython[parallel]"
-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_.
+or manual
-Dependencies for IPython.kernel.zmq
-===================================
+.. code-block:: bash
-pyzmq
------
+ pip install 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.
+PyZMQ provides wheels for current Python on OS X and Windows, so installing pyzmq will typically not require compilation.
-IPython.kernel.zmq depends on pyzmq >= 2.2.
+IPython.parallel can use SSH tunnels, which require paramiko_ on Windows.
-Dependencies for the IPython QT console
+Dependencies for the IPython Qt console
=======================================
-pyzmq
------
+pyzmq_, pygments_, PyQt_ (or PySide_)
-Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
-PyZMQ.
+Shortcut:
-Qt
---
+.. code-block:: bash
-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
-`_.
+ pip install "ipython[qtconsole]"
-pygments
---------
+or manual
+
+.. code-block:: bash
+
+ pip install pyzmq pygments
-The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
-project, which is pip install-able.
+PyQt/PySide are not pip installable, so generally must be installed via system package managers (or conda).
.. _installnotebook:
Dependencies for the IPython HTML notebook
==========================================
-The IPython notebook is a notebook-style web interface to IPython and can be
-started with the command ``ipython notebook``.
+The HTML notebook is a complex web application with quite a few dependencies:
-pyzmq
------
+pyzmq_, jinja2_, tornado_, mistune_, jsonschema_, pygments_, terminado_
-Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console`
-packages, the HTML notebook requires ZeroMQ and PyZMQ.
+Shortcut:
-Tornado
--------
+.. code-block:: bash
-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.
+ pip install "ipython[notebook]"
-Jinja
------
+or manual:
-The IPython notebook uses the Jinja_ templating tool to render HTML pages.
+.. code-block:: bash
+ pip install pyzmq jinja2 tornado mistune jsonschema pygments terminado_
+
+The IPython notebook is a notebook-style web interface to IPython and can be
+started with the command ``ipython notebook``.
MathJax
-------
@@ -360,20 +315,19 @@ 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()
+ python -m IPython.external.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
+ 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
+ python -m IPython.external.mathjax -d /some/other/mathjax
-By default Mathjax will be installed in your ipython profile directory, but you
+By default Mathjax will be installed in your ipython directory, but you
can make system wide install, please refer to the documentation and helper function
of :mod:`IPython.external.mathjax`
@@ -395,6 +349,7 @@ The following browsers are unsupported:
* Chrome < 13
* Opera (any): CSS issues, but execution might work
* Internet Explorer < 10
+* Internet Explorer ≥ 10 (same as Opera)
The following specific combinations are known **NOT** to work:
@@ -409,11 +364,7 @@ expect there will be some CSS issues related to the flexible box model.
Dependencies for nbconvert (converting notebooks to various formats)
====================================================================
-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.
+For converting markdown to formats other than HTML, nbconvert uses Pandoc_ (1.12.1 or later).
To install pandoc on Linux, you can generally use your package manager::
@@ -432,3 +383,9 @@ On other platforms, you can get pandoc from `their website