diff --git a/docs/source/install/install.rst b/docs/source/install/install.rst index 5b21e5b..04bfaa3 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,16 +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 -to simply use :command:`pip`: +If you have :mod:`pip`, the easiest way of getting IPython is: .. code-block:: bash @@ -93,7 +84,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 @@ -105,42 +96,14 @@ just grab the latest stable build of IPython from `here 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`. -Windows -------- - -As mentioned above, on Windows, IPython requires :mod:`setuptools`, 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: - -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. - -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 +112,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 +152,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 +171,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 +181,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,8 +193,8 @@ 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 -``pip`` command), the correct readline should be installed if you specify the `terminal` +When IPython is installed with :mod:`pip`, +the correct readline should be installed if you specify the `terminal` optional dependencies: .. code-block:: bash @@ -270,84 +232,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 -The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_ -project, which is pip install-able. +.. code-block:: bash + + pip install pyzmq pygments + +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,21 +305,20 @@ 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 -can make system wide install, please refer to the documentation and helper function +By default MathJax will be installed in your ipython directory, but you +can install MathJax system-wide. Please refer to the documentation of :mod:`IPython.external.mathjax` Browser Compatibility @@ -395,25 +339,15 @@ 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: - -* 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 `_ 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. +Using Safari with HTTPS and an untrusted certificate is known to not work (websockets will fail). 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 +366,9 @@ On other platforms, you can get pandoc from `their website