install.txt
401 lines
| 13.5 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:: | ||||
|
r3672 | Officially, IPython supports Python versions 2.6 and 2.7. | ||
|
r2113 | |||
|
r3672 | IPython 0.11 has a hard syntax dependency on 2.6, and will no longer work | ||
|
r4881 | on Python <= 2.5. You can find older versions of IPython which supported | ||
Python <= 2.5 `here <http://archive.ipython.org/release/>`_ | ||||
|
r1690 | |||
|
r1753 | Some of the installation approaches use the :mod:`setuptools` package and its | ||
:command:`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 :mod:`setuptools` can be found on its | ||||
website. | ||||
|
r4097 | .. note:: | ||
On Windows, IPython *does* depend on :mod:`setuptools`, and it is recommended | ||||
that you install the :mod:`distribute` package, which improves | ||||
:mod:`setuptools` and fixes various bugs. | ||||
We hope to remove this dependency in 0.12. | ||||
|
r1753 | More general information about installing Python packages can be found in | ||
Python's documentation at http://www.python.org/doc/. | ||||
|
r1690 | |||
|
r1729 | Quickstart | ||
========== | ||||
|
r1866 | If you have :mod:`setuptools` installed and you are on OS X or Linux (not | ||
Windows), the following will download and install IPython *and* the main | ||||
|
r2276 | optional dependencies: | ||
|
r1729 | |||
|
r2276 | .. code-block:: bash | ||
|
r3672 | $ easy_install ipython[zmq,test] | ||
|
r1729 | |||
|
r3672 | This will get pyzmq, which is needed for | ||
|
r1866 | IPython's parallel computing features as well as the nose package, which will | ||
|
r2277 | enable you to run IPython's test suite. | ||
To run IPython's test suite, use the :command:`iptest` command: | ||||
|
r2276 | |||
.. code-block:: bash | ||||
|
r1729 | |||
|
r2277 | $ iptest | ||
|
r1729 | |||
Read on for more specific details and instructions for Windows. | ||||
|
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 | ||||
|
r3768 | editing. If you install IPython with :mod:`setuptools`, (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 | ||||
------------------------------- | ||||
|
r1753 | If you have :mod:`setuptools` installed, the easiest way of getting IPython is | ||
|
r2276 | to simple 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 | ||||
------- | ||||
|
r4097 | .. note:: | ||
On Windows, IPython requires :mod:`setuptools` or :mod:`distribute`. | ||||
We hope to remove this dependency in 0.12. | ||||
|
r1866 | 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 | ||||
|
r2113 | shortcuts, which most users want. To get an installation with these, you can | ||
use any of the following alternatives: | ||||
|
r1690 | |||
|
r1866 | 1. Install using :command:`easy_install`. | ||
|
r1690 | |||
|
r3768 | 2. Install using our binary ``.exe`` Windows installer, which can be found | ||
|
r4880 | `here <http://ipython.org/download.html>`_ | ||
|
r1690 | |||
|
r1866 | 3. Install from source, but using :mod:`setuptools` (``python setupegg.py | ||
|
r1754 | install``). | ||
|
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 | ||||
|
r2555 | 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. | ||||
.. _this bug report: https://bugs.launchpad.net/ipython/+bug/382214 | ||||
|
r2113 | |||
|
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 | |||
|
r1866 | 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. | ||||
|
r1690 | |||
|
r1753 | 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 | ||||
|
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 | |||
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 | ||||
-------- | ||||
|
r1754 | In principle, all Python distributions should come with a working | ||
:mod:`readline` module. But, reality is not quite that simple. There are two | ||||
common situations where you won't have a working :mod:`readline` module: | ||||
|
r1690 | |||
* If you are using the built-in Python on Mac OS X. | ||||
* If you are running Windows, which doesn't have a :mod:`readline` module. | ||||
|
r3768 | When IPython is installed with :mod:`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. | ||||
|
r3058 | |||
|
r1753 | On OS X, the built-in Python doesn't not have :mod:`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, | ||||
|
r3058 | 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 | ||||
:mod:`readline` module. We will *not* consider completion/history problems to | ||||
be bugs for IPython if you are using libedit. | ||||
|
r1753 | |||
|
r3058 | To get a working :mod:`readline` module, just do (with :mod:`setuptools` | ||
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 | |||
|
r1753 | If needed, the readline egg can be build and installed from source (see the | ||
|
r4880 | wiki page at | ||
http://web.archive.org/web/20090614162410/ipython.scipy.org/moin/InstallationOSXLeopard). | ||||
|
r1690 | |||
|
r1788 | On Windows, you will need the PyReadline module. PyReadline is a separate, | ||
|
r1753 | Windows only implementation of readline that uses native Windows calls through | ||
|
r1788 | :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary | ||
|
r3768 | installer available `here <https://launchpad.net/pyreadline/+download>`_. | ||
|
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 | |||
|
r3672 | IPython.parallel provides a nice architecture for parallel computing. The | ||
main focus of this architecture is on interactive parallel computing. These | ||||
|
r4524 | features require just one package: PyZMQ. See the next section for PyZMQ | ||
|
r3672 | details. | ||
|
r1690 | |||
|
r2276 | On a Unix style platform (including OS X), if you want to use | ||
:mod:`setuptools`, 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 | ||||
----- | ||||
Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console` packages, | ||||
the HTML notebook requires ZeroMQ and PyZMQ. | ||||
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, | ||||
we do include a utility to aid in downloading MathJax and installing it into | ||||
the proper location:: | ||||
|
r4665 | |||
from IPython.external.mathjax import install_mathjax | ||||
install_mathjax() | ||||
|
r4673 | 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. | ||||
|
r4665 | |||
|
r4673 | Browser Compatibility | ||
--------------------- | ||||
|
r4524 | |||
The notebook uses WebSockets and the flexible box model. These features are | ||||
available in the following browsers: | ||||
* Chrome. | ||||
* Safari. | ||||
|
r4673 | * Firefox 4 and 5. These browsers have WebSocket support, but it is disabled by | ||
|
r4524 | default. 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``. | ||||
* Firefox 6. Starting with version 6, Firefox has WebSocket support enabled by default. | ||||
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 | ||||