install.rst
433 lines
| 14.4 KiB
| text/x-rst
|
RstLexer
|
r12147 | IPython requires Python 2.7 or ≥ 3.3. | ||
|
r1753 | |||
|
r4097 | .. note:: | ||
|
r12147 | If you need to use Python 2.6 or 3.2, you can find IPython 1.0 | ||
|
r12090 | `here <http://archive.ipython.org/release/>`__. | ||
|
r6602 | |||
|
r1729 | Quickstart | ||
========== | ||||
|
r12090 | If you have :mod:`setuptools`, | ||
the quickest way to get up and running with IPython is: | ||||
|
r1729 | |||
|
r2276 | .. code-block:: bash | ||
|
r11491 | $ easy_install ipython[all] | ||
|
r6602 | |||
|
r12090 | This will download and install IPython and its main optional dependencies: | ||
|
r1729 | |||
|
r9238 | - jinja2, needed for the notebook | ||
|
r11491 | - sphinx, needed for nbconvert | ||
|
r6602 | - pyzmq, needed for IPython's parallel computing features, qt console and | ||
|
r12090 | notebook | ||
- pygments, used by nbconvert and the Qt console for syntax highlighting | ||||
|
r6602 | - tornado, needed by the web-based notebook | ||
|
r12090 | - nose, used by the test suite | ||
- readline (on OS X) or pyreadline (on Windows), needed for the terminal | ||||
|
r2277 | |||
To run IPython's test suite, use the :command:`iptest` command: | ||||
|
r2276 | |||
.. code-block:: bash | ||||
|
r1729 | |||
|
r2277 | $ iptest | ||
|
r1729 | |||
|
r12090 | .. note:: | ||
.. code-block:: bash | ||||
$ pip install ipython[all] | ||||
|
r6602 | |||
|
r12090 | will also work in many cases, but it will ignore the binary eggs | ||
of packages such as pyzmq and readline, | ||||
which may be required for some users on Windows or OS X. | ||||
Overview | ||||
======== | ||||
This document describes in detail the steps required to install IPython, | ||||
and its various optional dependencies. | ||||
For a few quick ways to get started with package managers or full Python distributions, | ||||
see `the install page <http://ipython.org/install.html>`_ of the IPython website. | ||||
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. | ||||
IPython and most dependencies can be installed via :command:`easy_install`, | ||||
provided by the :mod:`setuptools` package, or :command:`pip`. | ||||
In many scenarios, this is the most simplest method of installing Python packages. | ||||
More information about :mod:`setuptools` can be found on | ||||
`its PyPI page <http://pypi.python.org/pypi/setuptools>`__. | ||||
.. 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 <http://docs.python.org>`_. | ||||
|
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 | ||||
|
r12089 | editing. If you install IPython with :mod:`setuptools`, (e.g. with | ||
|
r6602 | `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 | |||
|
r12089 | Installation using easy_install or pip | ||
-------------------------------------- | ||||
|
r1690 | |||
|
r12090 | If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is | ||
to simply use :command:`easy_install` or :command:`pip`: | ||||
|
r1753 | |||
|
r2276 | .. code-block:: bash | ||
|
r12090 | $ pip install ipython | ||
|
r1690 | |||
That's it. | ||||
|
r12090 | .. note:: | ||
Many prefer :command:`pip` to :command:`easy_install`, but it ignores eggs (binary Python packages). | ||||
This mainly affects pyzmq and readline, which are compiled packages and provide | ||||
binary eggs. If you use :command:`pip` to install these packages, | ||||
it will always compile from source, which may not succeed. | ||||
|
r1690 | 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 | ||||
------- | ||||
|
r12089 | As mentioned above, on Windows, IPython requires :mod:`setuptools`, and it also | ||
|
r6598 | 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 | |||
|
r12089 | 1. Install `setuptools <http://pypi.python.org/pypi/setuptools>`_. | ||
|
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 | ||
|
r12090 | $ git clone --recursive 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 | ||
|
r12089 | 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 | |||
|
r12090 | |||
|
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) | ||||
|
r1866 | If you are comfortable installing these things yourself, have at it, otherwise | ||
read on for more details. | ||||
|
r1690 | |||
|
r14705 | IPython uses several other modules, such as pexpect_ and path.py, if they are | ||
installed on your system, but it can also use bundled versions from | ||||
:mod:`IPython.external`, so there's no need to install them separately. | ||||
|
r1690 | readline | ||
-------- | ||||
|
r13891 | As indicated above, on Windows, to get full functionality in the console | ||
version of IPython, PyReadline is needed. | ||||
|
r6598 | 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 | ||||
|
r12090 | <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 | |||
|
r12089 | To get a working :mod:`readline` module, just do (with :mod:`setuptools` | ||
|
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 | |||
|
r12089 | When IPython is installed with :mod:`setuptools`, (e.g. using the | ||
|
r6598 | ``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 | ||||
|
r12089 | do not use setuptools, 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 | ||||
|
r12090 | simplest way of getting nose is to use :command:`easy_install` or :command:`pip`: | ||
|
r2276 | |||
.. code-block:: bash | ||||
|
r1690 | |||
|
r12090 | $ pip install nose | ||
|
r1690 | |||
|
r2276 | Another way of getting this is to do: | ||
|
r1690 | |||
|
r2276 | .. code-block:: bash | ||
|
r12090 | $ pip 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 | |||
|
r3672 | Dependencies for IPython.parallel (parallel computing) | ||
====================================================== | ||||
|
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 | ||
|
r12089 | :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 | |||
|
r9455 | Dependencies for IPython.kernel.zmq | ||
|
r11491 | =================================== | ||
|
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 | |||
|
r9455 | IPython.kernel.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 | |||
|
r9455 | Also with 0.11, a new GUI was added using the work in :mod:`IPython.kernel.zmq`, which | ||
|
r4779 | 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 | ||||
|
r12098 | started with the command ``ipython notebook``. | ||
|
r4524 | |||
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 | |||
|
r9238 | Jinja | ||
----- | ||||
The IPython notebook uses the Jinja_ templating tool to render HTML pages. | ||||
|
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:: | ||||
|
r9238 | python -m IPython.external.mathjax -d /some/other/mathjax | ||
|
r8154 | |||
|
r8507 | By default Mathjax will be installed in your ipython profile directory, but you | ||
|
r9238 | can make system wide install, please refer to the documentation and helper function | ||
of :mod:`IPython.external.mathjax` | ||||
|
r4665 | |||
|
r4673 | Browser Compatibility | ||
--------------------- | ||||
|
r4524 | |||
|
r9564 | The IPython notebook is officially supported on the following browers: | ||
* 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](http://help.diigo.com/tools/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. | ||||
|
r4524 | |||
|
r11491 | Dependencies for nbconvert (converting notebooks to various formats) | ||
==================================================================== | ||||
pandoc | ||||
------ | ||||
|
r12842 | The most important dependency of nbconvert is Pandoc_ 1.10 or later, a document format translation program. | ||
|
r11491 | 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 <http://johnmacfarlane.net/pandoc/installing.html>`_. | ||||
|
r4779 | .. _ZeroMQ: http://www.zeromq.org | ||
.. _PyZMQ: https://github.com/zeromq/pyzmq | ||||
.. _paramiko: https://github.com/robey/paramiko | ||||
.. _pygments: http://pygments.org | ||||
|
r14705 | .. _pexpect: http://pexpect.readthedocs.org/en/latest/ | ||
|
r9238 | .. _Jinja: http://jinja.pocoo.org | ||
|
r11491 | .. _Sphinx: http://sphinx-doc.org | ||
.. _pandoc: http://johnmacfarlane.net/pandoc | ||||
|
r4779 | .. _Tornado: http://www.tornadoweb.org | ||
.. _MathJax: http://www.mathjax.org | ||||