install.rst
180 lines
| 5.7 KiB
| text/x-rst
|
RstLexer
Thomas Kluyver
|
r12147 | IPython requires Python 2.7 or ≥ 3.3. | ||
Fernando Perez
|
r1753 | |||
Thomas Kluyver
|
r21579 | .. seealso:: | ||
MinRK
|
r4097 | |||
Thomas Kluyver
|
r21579 | `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`__ | ||
The Notebook, nbconvert, and many other former pieces of IPython are now | ||||
part of Project Jupyter. | ||||
Min RK
|
r20524 | |||
Fernando Perez
|
r6602 | |||
Brian Granger
|
r1729 | Quickstart | ||
========== | ||||
Min RK
|
r20524 | If you have :mod:`pip`, | ||
MinRK
|
r12090 | the quickest way to get up and running with IPython is: | ||
Brian Granger
|
r1729 | |||
Brian Granger
|
r2276 | .. code-block:: bash | ||
Thomas Kluyver
|
r21579 | $ pip install ipython | ||
Fernando Perez
|
r6602 | |||
Thomas Kluyver
|
r21579 | To use IPython with notebooks or the Qt console, you should also install | ||
``jupyter``. | ||||
Brian Granger
|
r2277 | |||
To run IPython's test suite, use the :command:`iptest` command: | ||||
Brian Granger
|
r2276 | |||
.. code-block:: bash | ||||
Brian Granger
|
r1729 | |||
Brian Granger
|
r2277 | $ iptest | ||
Brian Granger
|
r1729 | |||
MinRK
|
r12090 | |||
Overview | ||||
======== | ||||
Thomas Kluyver
|
r21579 | This document describes in detail the steps required to install IPython. | ||
MinRK
|
r12090 | 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. | ||||
Please let us know if you have problems installing IPython or any of its dependencies. | ||||
MinRK
|
r16708 | IPython and most dependencies can be installed via :command:`pip`. | ||
In many scenarios, this is the simplest method of installing Python packages. | ||||
More information about :mod:`pip` can be found on | ||||
`its PyPI page <http://pypi.python.org/pypi/pip>`__. | ||||
MinRK
|
r12090 | |||
More general information about installing Python packages can be found in | ||||
`Python's documentation <http://docs.python.org>`_. | ||||
Brian Granger
|
r1690 | Installing IPython itself | ||
========================= | ||||
Fernando Perez
|
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 | ||||
Min RK
|
r20524 | 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`. | ||||
Brian Granger
|
r1690 | |||
MinRK
|
r16708 | Installation using pip | ||
---------------------- | ||||
Brian Granger
|
r1690 | |||
Min RK
|
r20534 | If you have :mod:`pip`, the easiest way of getting IPython is: | ||
Fernando Perez
|
r1753 | |||
Brian Granger
|
r2276 | .. code-block:: bash | ||
MinRK
|
r12090 | $ pip install ipython | ||
Brian Granger
|
r1690 | |||
That's it. | ||||
MinRK
|
r12090 | |||
Brian Granger
|
r1690 | Installation from source | ||
------------------------ | ||||
MinRK
|
r16708 | If you don't want to use :command:`pip`, or don't have it installed, | ||
Thomas Kluyver
|
r21579 | grab the latest stable tarball of IPython `from PyPI | ||
<https://pypi.python.org/pypi/ipython>`__. Then do the following: | ||||
Brian Granger
|
r2276 | |||
.. code-block:: bash | ||||
Brian Granger
|
r1690 | |||
Brian Granger
|
r2277 | $ tar -xzf ipython.tar.gz | ||
$ cd ipython | ||||
$ python setup.py install | ||||
Fernando Perez
|
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`. | ||||
Brian Granger
|
r1690 | |||
Installing the development version | ||||
---------------------------------- | ||||
Fernando Perez
|
r1753 | It is also possible to install the development version of IPython from our | ||
MinRK
|
r3768 | `Git <http://git-scm.com/>`_ source code repository. To do this you will | ||
Min RK
|
r20524 | need to have Git installed on your system. Then do: | ||
Fernando Perez
|
r1753 | |||
Brian Granger
|
r2276 | .. code-block:: bash | ||
MinRK
|
r12090 | $ git clone --recursive https://github.com/ipython/ipython.git | ||
Brian Granger
|
r2277 | $ cd ipython | ||
$ python setup.py install | ||||
Brian Granger
|
r1690 | |||
Fernando Perez
|
r1753 | Some users want to be able to follow the development branch as it changes. If | ||
Min RK
|
r20524 | you have :mod:`pip`, you can replace the last step by: | ||
Brian Granger
|
r2276 | |||
.. code-block:: bash | ||||
Brian Granger
|
r1690 | |||
Min RK
|
r20524 | $ pip install -e . | ||
Brian Granger
|
r1690 | |||
Fernando Perez
|
r1754 | This creates links in the right places and installs the command line script to | ||
Nikolay Koldunov
|
r16319 | the appropriate places. | ||
Nikolay Koldunov
|
r16317 | |||
Min RK
|
r20524 | Then, if you want to update your IPython at any time, do: | ||
Brian Granger
|
r2276 | |||
.. code-block:: bash | ||||
Fernando Perez
|
r1753 | |||
MinRK
|
r3768 | $ git pull | ||
Brian Granger
|
r1690 | |||
Thomas Kluyver
|
r21579 | .. _dependencies: | ||
Nikolay Koldunov
|
r16319 | |||
Thomas Kluyver
|
r21579 | Dependencies | ||
============ | ||||
MinRK
|
r12090 | |||
Thomas Kluyver
|
r21579 | IPython relies on a number of other Python packages. Installing using a package | ||
manager like pip or conda will ensure the necessary packages are installed. If | ||||
you install manually, it's up to you to make sure dependencies are installed. | ||||
They're not listed here, because they may change from release to release, so a | ||||
static list will inevitably get out of date. | ||||
Brian Granger
|
r1690 | |||
Thomas Kluyver
|
r21579 | It also has one key non-Python dependency which you may need to install separately. | ||
Thomas Kluyver
|
r14705 | |||
Brian Granger
|
r1690 | readline | ||
-------- | ||||
Thomas Kluyver
|
r21579 | IPython's terminal interface relies on readline to provide features like tab | ||
completion and history navigation. If you only want to use IPython as a kernel | ||||
for Jupyter notebooks and other frontends, you don't need readline. | ||||
**On Windows**, to get full console functionality, *PyReadline* is required. | ||||
Fernando Perez
|
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 | ||||
MinRK
|
r12090 | <http://pypi.python.org/pypi/pyreadline>`__. | ||
Fernando Perez
|
r3058 | |||
Thomas Kluyver
|
r21579 | **On OS X**, if you are using the built-in Python shipped by Apple, you will be | ||
MinRK
|
r16708 | missing a proper readline implementation as Apple ships instead a library called | ||
Fernando Perez
|
r6598 | ``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. | ||||
Fernando Perez
|
r3058 | |||
MinRK
|
r16708 | Therefore, IPython on OS X depends on the :mod:`gnureadline` module. | ||
Thomas Kluyver
|
r21579 | We will *not* consider completion/history problems to be bugs for IPython if you | ||
are using libedit. | ||||
Fernando Perez
|
r1753 | |||
Min RK
|
r20524 | To get a working :mod:`readline` module on OS X, do (with :mod:`pip` | ||
Fernando Perez
|
r3058 | installed): | ||
Brian Granger
|
r1690 | |||
Brian Granger
|
r2276 | .. code-block:: bash | ||
MinRK
|
r16708 | $ pip install gnureadline | ||
Brian Granger
|
r1690 | |||
Brian Granger
|
r2277 | .. note:: | ||
Brian Granger
|
r1690 | |||
MinRK
|
r16708 | 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. | ||||
Brian Granger
|
r1690 | |||
Min RK
|
r20534 | When IPython is installed with :mod:`pip`, | ||
the correct readline should be installed if you specify the `terminal` | ||||
MinRK
|
r16708 | optional dependencies: | ||
.. code-block:: bash | ||||
gporras
|
r18023 | $ pip install "ipython[terminal]" | ||
Brian Granger
|
r1690 | |||
Thomas Kluyver
|
r21579 | **On Linux**, readline is normally installed by default. If not, install it | ||
from your system package manager. If you are compiling your own Python, make | ||||
sure you install the readline development headers first. | ||||
Brian Granger
|
r1690 | |||