install.txt
388 lines
| 12.8 KiB
| text/plain
|
TextLexer
|
r1690 | Overview | ||
======== | ||||
|
r1753 | 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. | ||||
|
r1690 | |||
Please let us know if you have problems installing IPython or any of its | ||||
|
r4881 | dependencies. Officially, IPython requires Python 2.6, 2.7, 3.1, or 3.2. | ||
|
r1690 | |||
.. warning:: | ||||
|
r5439 | 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 <http://archive.ipython.org/release/>`_ | ||||
|
r1690 | |||
|
r6598 | Some of the installation approaches use the :mod:`distribute` package and its | ||
|
r1753 | :command:`easy_install` command line program. In many scenarios, this provides | ||
|
r6598 | the most simple method of installing IPython and its dependencies. More | ||
|
r6608 | information about :mod:`distribute` can be found on `its PyPI page | ||
<http://pypi.python.org/pypi/distribute>`__. | ||||
|
r1753 | |||
|
r4097 | .. note:: | ||
|
r6598 | On Windows, IPython has a hard dependency on :mod:`distribute`. We hope to | ||
change this in the future, but for now on Windows, you *must* install | ||||
:mod:`distribute`. | ||||
|
r4097 | |||
|
r1753 | More general information about installing Python packages can be found in | ||
|
r6598 | `Python's documentation <http://docs.python.org>`_. | ||
|
r1690 | |||
|
r6602 | |||
|
r1729 | Quickstart | ||
========== | ||||
|
r6598 | If you have :mod:`distribute` installed and you are on OS X or Linux (not | ||
|
r1866 | Windows), the following will download and install IPython *and* the main | ||
|
r2276 | optional dependencies: | ||
|
r1729 | |||
|
r2276 | .. code-block:: bash | ||
|
r6602 | $ easy_install ipython[zmq,qtconsole,notebook,test] | ||
This will get: | ||||
|
r1729 | |||
|
r6602 | - 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. | ||||
|
r2277 | |||
To run IPython's test suite, use the :command:`iptest` command: | ||||
|
r2276 | |||
.. code-block:: bash | ||||
|
r1729 | |||
|
r2277 | $ iptest | ||
|
r1729 | |||
|
r6602 | |||
|
r1690 | Installing IPython itself | ||
========================= | ||||
|
r1753 | 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 :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 | ||||
|
r6602 | editing. If you install IPython with :mod:`distribute`, (e.g. with | ||
`easy_install`), 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`. | ||||
|
r1690 | |||
Installation using easy_install | ||||
------------------------------- | ||||
|
r6598 | If you have :mod:`distribute` installed, the easiest way of getting IPython is | ||
|
r6607 | to simply use :command:`easy_install`: | ||
|
r1753 | |||
|
r2276 | .. code-block:: bash | ||
|
r2277 | $ easy_install ipython | ||
|
r1690 | |||
That's it. | ||||
Installation from source | ||||
------------------------ | ||||
|
r1753 | If you don't want to use :command:`easy_install`, or don't have it installed, | ||
just grab the latest stable build of IPython from `here | ||||
|
r4881 | <http://ipython.org/download.html>`_. Then do the following: | ||
|
r2276 | |||
.. code-block:: bash | ||||
|
r1690 | |||
|
r2277 | $ tar -xzf ipython.tar.gz | ||
$ cd ipython | ||||
$ python setup.py install | ||||
|
r1753 | |||
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`. | ||||
|
r1690 | |||
Windows | ||||
------- | ||||
|
r6598 | As mentioned above, on Windows, IPython requires :mod:`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: | ||||
|
r4097 | |||
|
r6598 | 1. Install `distribute <http://pypi.python.org/pypi/distribute>`_. | ||
|
r4097 | |||
|
r6598 | 2. Install `pyreadline <http://pypi.python.org/pypi/pyreadline>`_. You can use | ||
the command ``easy_install pyreadline`` from a terminal, or the binary | ||||
installer appropriate for your platform from the PyPI page. | ||||
|
r1690 | |||
|
r6598 | 3. Install IPython itself, which you can download from `PyPI | ||
<http://pypi.python.org/pypi/ipython>`_ or from `our site | ||||
<http://ipython.org/download.html>`_. Note that on Windows 7, you *must* | ||||
right-click and 'Run as administrator' for the Start menu shortcuts to be | ||||
created. | ||||
|
r1690 | |||
|
r2276 | IPython by default runs in a terminal window, but the normal terminal | ||
|
r2113 | 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 | ||||
|
r1690 | Installing the development version | ||
---------------------------------- | ||||
|
r1753 | It is also possible to install the development version of IPython from our | ||
|
r3768 | `Git <http://git-scm.com/>`_ source code repository. To do this you will | ||
need to have Git installed on your system. Then just do: | ||||
|
r1753 | |||
|
r2276 | .. code-block:: bash | ||
|
r3768 | $ git clone https://github.com/ipython/ipython.git | ||
|
r2277 | $ cd ipython | ||
$ python setup.py install | ||||
|
r1690 | |||
|
r1753 | Some users want to be able to follow the development branch as it changes. If | ||
|
r6598 | you have :mod:`distribute` installed, this is easy. Simply replace the last | ||
|
r2276 | step by: | ||
.. code-block:: bash | ||||
|
r1690 | |||
|
r2277 | $ python setupegg.py develop | ||
|
r1690 | |||
|
r1754 | 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, | ||||
|
r2276 | just do: | ||
.. code-block:: bash | ||||
|
r1753 | |||
|
r3768 | $ git pull | ||
|
r1690 | |||
|
r6598 | |||
|
r1690 | Basic optional dependencies | ||
=========================== | ||||
|
r1866 | There are a number of basic optional dependencies that most users will want to | ||
get. These are: | ||||
|
r1690 | |||
* readline (for command line editing, tab completion, etc.) | ||||
* nose (to run the IPython test suite) | ||||
* pexpect (to use things like irunner) | ||||
|
r1866 | If you are comfortable installing these things yourself, have at it, otherwise | ||
read on for more details. | ||||
|
r1690 | |||
readline | ||||
-------- | ||||
|
r6598 | As indicated above, on Windows, PyReadline is a *mandatory* dependency. | ||
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 | ||||
<http://pypi.python.org/pypi/pyreadline>`_. | ||||
|
r3058 | |||
|
r6598 | On OSX, if you are using the built-in Python shipped by Apple, you will be | ||
missing a full 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. | ||||
|
r3058 | |||
Therefore, we *strongly* recommend that on OS X you get the full | ||||
:mod:`readline` module. We will *not* consider completion/history problems to | ||||
be bugs for IPython if you are using libedit. | ||||
|
r1753 | |||
|
r6598 | To get a working :mod:`readline` module, just do (with :mod:`distribute` | ||
|
r3058 | installed): | ||
|
r1690 | |||
|
r2276 | .. code-block:: bash | ||
|
r2277 | $ easy_install readline | ||
|
r1690 | |||
|
r2277 | .. note:: | ||
|
r1690 | |||
|
r3058 | 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. | ||||
|
r1690 | |||
|
r6598 | When IPython is installed with :mod:`distribute`, (e.g. using the | ||
``easy_install`` command), 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 distribute, you may have to install one of these packages yourself. | ||||
|
r1690 | |||
nose | ||||
---- | ||||
|
r1753 | 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 | ||||
|
r2276 | simplest way of getting nose, is to use :command:`easy_install`: | ||
.. code-block:: bash | ||||
|
r1690 | |||
|
r2277 | $ easy_install nose | ||
|
r1690 | |||
|
r2276 | Another way of getting this is to do: | ||
|
r1690 | |||
|
r2276 | .. code-block:: bash | ||
|
r2277 | $ easy_install ipython[test] | ||
|
r1690 | |||
|
r1753 | For more installation options, see the `nose website | ||
|
r2277 | <http://somethingaboutorange.com/mrl/projects/nose/>`_. | ||
Once you have nose installed, you can run IPython's test suite using the | ||||
iptest command: | ||||
|
r1753 | |||
|
r2276 | .. code-block:: bash | ||
|
r1690 | |||
|
r2277 | $ iptest | ||
|
r1690 | |||
pexpect | ||||
------- | ||||
|
r4779 | The pexpect_ package is used in IPython's :command:`irunner` script, as well as | ||
for managing subprocesses. IPython now includes a version of pexpect in | ||||
:mod:`IPython.external`, but if you have installed pexpect, IPython will use | ||||
|
r3768 | that instead. On Unix platforms (including OS X), just do: | ||
|
r2276 | |||
.. code-block:: bash | ||||
|
r1690 | |||
|
r2277 | $ easy_install pexpect | ||
|
r1690 | |||
Windows users are out of luck as pexpect does not run there. | ||||
|
r3672 | Dependencies for IPython.parallel (parallel computing) | ||
====================================================== | ||||
|
r1690 | |||
|
r3672 | :mod:`IPython.kernel` has been replaced by :mod:`IPython.parallel`, | ||
which uses ZeroMQ for all communication. | ||||
|
r1690 | |||
|
r6598 | 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. | ||||
|
r1690 | |||
|
r2276 | On a Unix style platform (including OS X), if you want to use | ||
|
r6598 | :mod:`distribute`, you can just do: | ||
|
r1753 | |||
|
r2276 | .. code-block:: bash | ||
|
r3672 | $ easy_install ipython[zmq] # will include pyzmq | ||
|
r1690 | |||
|
r3672 | 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 | ||||
|
r4779 | support tunneling with paramiko_. | ||
|
r1690 | |||
|
r3672 | Dependencies for IPython.zmq | ||
============================ | ||||
|
r3591 | |||
pyzmq | ||||
----- | ||||
IPython 0.11 introduced some new functionality, including a two-process | ||||
|
r4779 | 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, | ||||
|
r4028 | pyzmq has eggs that include ZeroMQ itself. | ||
|
r3672 | |||
|
r4028 | IPython.zmq depends on pyzmq >= 2.1.4. | ||
|
r3591 | |||
|
r4524 | Dependencies for the IPython QT console | ||
======================================= | ||||
|
r3591 | |||
|
r4710 | pyzmq | ||
----- | ||||
|
r4779 | Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and | ||
PyZMQ. | ||||
|
r4710 | |||
|
r4171 | Qt | ||
-- | ||||
|
r3591 | |||
|
r4779 | Also with 0.11, a new GUI was added using the work in :mod:`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 | ||||
<http://www.riverbankcomputing.co.uk/>`_, or `PySide | ||||
<http://www.pyside.org/>`_, from Nokia. | ||||
|
r3591 | |||
pygments | ||||
-------- | ||||
|
r4779 | The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_ | ||
project, which is easy_install-able. | ||||
|
r4856 | .. _installnotebook: | ||
|
r3591 | |||
|
r4524 | 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``. | ||||
pyzmq | ||||
----- | ||||
|
r6598 | Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console` | ||
packages, the HTML notebook requires ZeroMQ and PyZMQ. | ||||
|
r4524 | |||
Tornado | ||||
------- | ||||
|
r4856 | 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. | ||||
|
r4779 | |||
|
r4524 | |||
|
r4665 | MathJax | ||
------- | ||||
|
r4779 | 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, | ||||
|
r8154 | you can install MathJax locally. | ||
A quick and easy method is to install it from a python session:: | ||||
|
r4665 | |||
from IPython.external.mathjax import install_mathjax | ||||
install_mathjax() | ||||
|
r8154 | If you need tighter configuration control, you can download your own copy | ||
|
r8670 | of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link. | ||
|
r8154 | When you have the file stored locally, install it with:: | ||
|
r8670 | python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip | ||
|
r8154 | |||
For unusual needs, IPython can tell you what directory it wants to find MathJax in:: | ||||
python -m IPython.external.mathjax -d | ||||
|
r8507 | By default Mathjax will be installed in your ipython profile directory, but you | ||
can make system wide install, please refere to the documentation and helper function | ||||
of IPython.external.mathjax | ||||
|
r4665 | |||
|
r4673 | Browser Compatibility | ||
--------------------- | ||||
|
r4524 | |||
The notebook uses WebSockets and the flexible box model. These features are | ||||
available in the following browsers: | ||||
|
r5439 | * 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``. | ||||
|
r4524 | |||
Internet Explorer 9 does not support WebSockets or the flexible box model, but | ||||
these features should appear in Internet Explorer 10. | ||||
|
r4779 | .. _ZeroMQ: http://www.zeromq.org | ||
.. _PyZMQ: https://github.com/zeromq/pyzmq | ||||
.. _paramiko: https://github.com/robey/paramiko | ||||
.. _pygments: http://pygments.org | ||||
.. _pexpect: http://www.noah.org/wiki/Pexpect | ||||
.. _Tornado: http://www.tornadoweb.org | ||||
.. _MathJax: http://www.mathjax.org | ||||